Python: Fix WorkflowAgent event handling and kwargs forwarding (#2946 )

* Fix kwargs propagation through workflow.as_agent() * Fix WorkflowAgent to respect AgentExecutor output_response setting
Bump Azure.AI.AgentServer.AgentFramework from 1.0.0-beta.4 to 1.0.0-beta.5 (#2854 )
2026-06-16 21:04:09 +08:00 · 2025-12-18 19:35:07 +00:00 · 2025-12-18 18:36:13 +00:00 · 2025-12-18 17:25:54 +00:00 · 2025-12-18 17:25:36 +00:00 · 2025-12-18 17:10:55 +00:00
234 changed files with 15616 additions and 6811 deletions
@@ -839,7 +839,7 @@ var agentOptions = new ChatClientAgentRunOptions(new ChatOptions
 {
    MaxOutputTokens = 8000,
    // Breaking glass to access provider-specific options
-    RawRepresentationFactory = (_) => new OpenAI.Responses.ResponseCreationOptions()
+    RawRepresentationFactory = (_) => new OpenAI.Responses.CreateResponseOptions()
    {
        ReasoningOptions = new()
        {
@@ -35,7 +35,8 @@ jobs:
      contents: read
      pull-requests: read
    outputs:
-      dotnetChanges: ${{ steps.filter.outputs.dotnet}}
+      dotnetChanges: ${{ steps.filter.outputs.dotnet }}
+      cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
    steps:
      - uses: actions/checkout@v6
      - uses: dorny/paths-filter@v3
@@ -44,10 +45,15 @@ jobs:
          filters: |
            dotnet:
              - 'dotnet/**'
+            cosmosdb:
+              - 'dotnet/src/Microsoft.Agents.AI.CosmosNoSql/**'
      # run only if 'dotnet' files were changed
      - name: dotnet tests
        if: steps.filter.outputs.dotnet == 'true'
        run: echo "Dotnet file"
+      - name: dotnet CosmosDB tests
+        if: steps.filter.outputs.cosmosdb == 'true'
+        run: echo "Dotnet CosmosDB changes"
      # run only if not 'dotnet' files were changed
      - name: not dotnet tests
        if: steps.filter.outputs.dotnet != 'true'
@@ -77,6 +83,16 @@ jobs:
              dotnet
              python
              workflow-samples
+              
+      # Start Cosmos DB Emulator for all integration tests and only for unit tests when CosmosDB changes happened)
+      - name: Start Azure Cosmos DB Emulator
+        if: ${{ runner.os == 'Windows' && (needs.paths-filter.outputs.cosmosDbChanges == 'true' || (github.event_name != 'pull_request' && matrix.integration-tests)) }}
+        shell: pwsh
+        run: |
+          Write-Host "Launching Azure Cosmos DB Emulator"
+          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
+          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5.0.1
@@ -123,17 +139,7 @@ jobs:
          popd
          popd
          rm -rf "$TEMP_DIR"
-
-      # Start Cosmos DB Emulator for Cosmos-based unit tests (only on Windows)
-      - name: Start Azure Cosmos DB Emulator
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          Write-Host "Launching Azure Cosmos DB Emulator"
-          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
-          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
-
+          
      - name: Run Unit Tests
        shell: bash
        run: |
@@ -225,7 +231,7 @@ jobs:

      - name: Upload coverage report artifact
        if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
        with:
          name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
          path: ./TestResults/Reports # Directory containing files to upload
@@ -39,7 +39,7 @@ jobs:
        env:
          # Configure a constant location for the uv cache
          UV_CACHE_DIR: /tmp/.uv-cache
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
        with:
          path: ~/.cache/pre-commit
          key: pre-commit|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
@@ -21,7 +21,7 @@ jobs:
    steps:
      - uses: actions/checkout@v6
      - name: Download coverage report
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
        with:
          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
          run-id: ${{ github.event.workflow_run.id }}
@@ -38,7 +38,7 @@ jobs:
      - name: Run all tests with coverage report
        run: uv run poe all-tests-cov --cov-report=xml:python-coverage.xml -q --junitxml=pytest.xml
      - name: Upload coverage report
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
        with:
          path: |
            python/python-coverage.xml
@@ -10,19 +10,19 @@ model:
        temperature: 0.9
        topP: 0.95
    connection:
-        kind: ApiKey
-        key: =Env.OPENAI_API_KEY
+        kind: key
+        apiKey: =Env.OPENAI_APIKEY
 outputSchema:
    properties:
        language:
-            type: string
+            kind: string
            required: true
            description: The language of the answer.
        answer:
-            type: string
+            kind: string
            required: true
            description: The answer text.
        type:
-            type: string
+            kind: string
            required: true
            description: The type of the response.
@@ -0,0 +1,147 @@
+# Time-To-Live (TTL) for durable agent sessions
+
+## Overview
+
+The durable agents automatically maintain conversation history and state for each session. Without automatic cleanup, this state can accumulate indefinitely, consuming storage resources and increasing costs. The Time-To-Live (TTL) feature provides automatic cleanup of idle agent sessions, ensuring that sessions are automatically deleted after a period of inactivity.
+
+## What is TTL?
+
+Time-To-Live (TTL) is a configurable duration that determines how long an agent session state will be retained after its last interaction. When an agent session is idle (no messages sent to it) for longer than the TTL period, the session state is automatically deleted. Each new interaction with an agent resets the TTL timer, extending the session's lifetime.
+
+## Benefits
+
+- **Automatic cleanup**: No manual intervention required to clean up idle agent sessions
+- **Cost optimization**: Reduces storage costs by automatically removing unused session state
+- **Resource management**: Prevents unbounded growth of agent session state in storage
+- **Configurable**: Set TTL globally or per-agent type to match your application's needs
+
+## Configuration
+
+TTL can be configured at two levels:
+
+1. **Global default TTL**: Applies to all agent sessions unless overridden
+2. **Per-agent type TTL**: Overrides the global default for specific agent types
+
+Additionally, you can configure a **minimum deletion delay** that controls how frequently deletion operations are scheduled. The default value is 5 minutes, and the maximum allowed value is also 5 minutes.
+
+> [!NOTE]
+> Reducing the minimum deletion delay below 5 minutes can be useful for testing or for ensuring rapid cleanup of short-lived agent sessions. However, this can also increase the load on the system and should be used with caution.
+
+### Default values
+
+- **Default TTL**: 14 days
+- **Minimum TTL deletion delay**: 5 minutes (maximum allowed value, subject to change in future releases)
+
+### Configuration examples
+
+#### .NET
+
+```csharp
+// Configure global default TTL and minimum signal delay
+services.ConfigureDurableAgents(
+    options =>
+    {
+        // Set global default TTL to 7 days
+        options.DefaultTimeToLive = TimeSpan.FromDays(7);
+
+        // Add agents (will use global default TTL)
+        options.AddAIAgent(myAgent);
+    });
+
+// Configure per-agent TTL
+services.ConfigureDurableAgents(
+    options =>
+    {
+        options.DefaultTimeToLive = TimeSpan.FromDays(14); // Global default
+        
+        // Agent with custom TTL of 1 day
+        options.AddAIAgent(shortLivedAgent, timeToLive: TimeSpan.FromDays(1));
+        
+        // Agent with custom TTL of 90 days
+        options.AddAIAgent(longLivedAgent, timeToLive: TimeSpan.FromDays(90));
+        
+        // Agent using global default (14 days)
+        options.AddAIAgent(defaultAgent);
+    });
+
+// Disable TTL for specific agents by setting TTL to null
+services.ConfigureDurableAgents(
+    options =>
+    {
+        options.DefaultTimeToLive = TimeSpan.FromDays(14);
+        
+        // Agent with no TTL (never expires)
+        options.AddAIAgent(permanentAgent, timeToLive: null);
+    });
+```
+
+## How TTL works
+
+The following sections describe how TTL works in detail.
+
+### Expiration tracking
+
+Each agent session maintains an expiration timestamp in its internally managed state that is updated whenever the session processes a message:
+
+1. When a message is sent to an agent session, the expiration time is set to `current time + TTL`
+2. The runtime schedules a delete operation for the expiration time (subject to minimum delay constraints)
+3. When the delete operation runs, if the current time is past the expiration time, the session state is deleted. Otherwise, the delete operation is rescheduled for the next expiration time.
+
+### State deletion
+
+When an agent session expires, its entire state is deleted, including:
+
+- Conversation history
+- Any custom state data
+- Expiration timestamps
+
+After deletion, if a message is sent to the same agent session, a new session is created with a fresh conversation history.
+
+## Behavior examples
+
+The following examples illustrate how TTL works in different scenarios.
+
+### Example 1: Agent session expires after TTL
+
+1. Agent configured with 30-day TTL
+2. User sends message at Day 0 → agent session created, expiration set to Day 30
+3. No further messages sent
+4. At Day 30 → Agent session is deleted
+5. User sends message at Day 31 → New agent session created with fresh conversation history
+
+### Example 2: TTL reset on interaction
+
+1. Agent configured with 30-day TTL
+2. User sends message at Day 0 → agent session created, expiration set to Day 30
+3. User sends message at Day 15 → Expiration reset to Day 45
+4. User sends message at Day 40 → Expiration reset to Day 70
+5. Agent session remains active as long as there are regular interactions
+
+## Logging
+
+The TTL feature includes comprehensive logging to track state changes:
+
+- **Expiration time updated**: Logged when TTL expiration time is set or updated
+- **Deletion scheduled**: Logged when a deletion check signal is scheduled
+- **Deletion check**: Logged when a deletion check operation runs
+- **Session expired**: Logged when an agent session is deleted due to expiration
+- **TTL rescheduled**: Logged when a deletion signal is rescheduled
+
+These logs help monitor TTL behavior and troubleshoot any issues.
+
+## Best practices
+
+1. **Choose appropriate TTL values**: Balance between storage costs and user experience. Too short TTLs may delete active sessions, while too long TTLs may accumulate unnecessary state.
+
+2. **Use per-agent TTLs**: Different agents may have different usage patterns. Configure TTLs per-agent based on expected session lifetimes.
+
+3. **Monitor expiration logs**: Review logs to understand TTL behavior and adjust configuration as needed.
+
+4. **Test with short TTLs**: During development, use short TTLs (e.g., minutes) to verify TTL behavior without waiting for long periods.
+
+## Limitations
+
+- TTL is based on wall-clock time, not activity time. The expiration timer starts from the last message timestamp.
+- Deletion checks are durably scheduled operations and may have slight delays depending on system load.
+- Once an agent session is deleted, its conversation history cannot be recovered.
+- TTL deletion requires at least one worker to be available to process the deletion operation message.
@@ -209,6 +209,7 @@ dotnet_diagnostic.CA2000.severity = none # Call System.IDisposable.Dispose on ob
 dotnet_diagnostic.CA2225.severity = none # Operator overloads have named alternates
 dotnet_diagnostic.CA2227.severity = none # Change to be read-only by removing the property setter
 dotnet_diagnostic.CA2249.severity = suggestion # Consider using 'Contains' method instead of 'IndexOf' method
+dotnet_diagnostic.CA2252.severity = none # Requires preview
 dotnet_diagnostic.CA2253.severity = none # Named placeholders in the logging message template should not be comprised of only numeric characters
 dotnet_diagnostic.CA2253.severity = none # Named placeholders in the logging message template should not be comprised of only numeric characters
 dotnet_diagnostic.CA2263.severity = suggestion # Use generic overload
@@ -11,18 +11,18 @@
  </PropertyGroup>
  <ItemGroup>
    <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="11.0.0" />
+    <PackageVersion Include="Anthropic" Version="12.0.0" />
    <PackageVersion Include="Anthropic.Foundry" Version="0.1.0" />
    <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
    <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
-    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0-beta.440" />
+    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
    <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.3" />
-    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.4" />
+    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.5" />
+    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.5" />
    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.8" />
-    <PackageVersion Include="Azure.AI.OpenAI" Version="2.7.0-beta.2" />
+    <PackageVersion Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
    <PackageVersion Include="Azure.Identity" Version="1.17.1" />
    <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
    <!-- Google Gemini  -->
@@ -61,10 +61,9 @@
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
    <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.1.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.1.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.AzureAIInference" Version="10.0.0-preview.1.25559.3" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.1.0-preview.1.25608.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.1.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.1.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.1.1-preview.1.25612.2" />
    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
@@ -101,11 +100,10 @@
    <!-- MCP -->
    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
    <!-- Inference SDKs -->
-    <PackageVersion Include="Anthropic.SDK" Version="5.8.0" />
-    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.4.11" />
+    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5" />
    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
    <PackageVersion Include="OllamaSharp" Version="5.4.8" />
-    <PackageVersion Include="OpenAI" Version="2.7.0" />
+    <PackageVersion Include="OpenAI" Version="2.8.0" />
    <!-- Identity -->
    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
    <!-- Workflows -->
@@ -25,7 +25,6 @@
    <PackageReference Include="CommunityToolkit.Aspire.OllamaSharp" />
    <PackageReference Include="Microsoft.Extensions.AI" />
    <PackageReference Include="Microsoft.Extensions.AI.Abstractions" />
-    <PackageReference Include="Microsoft.Extensions.AI.AzureAIInference" />
    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
    <PackageReference Include="Microsoft.AspNetCore.OpenAPI" />
    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" />
@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

 using AgentWebChat.AgentHost.Utilities;
-using Azure;
-using Azure.AI.Inference;
 using Microsoft.Extensions.AI;
 using OllamaSharp;

@@ -24,7 +22,6 @@ public static class ChatClientExtensions
            ClientChatProvider.Ollama => builder.AddOllamaClient(connectionName, connectionInfo),
            ClientChatProvider.OpenAI => builder.AddOpenAIClient(connectionName, connectionInfo),
            ClientChatProvider.AzureOpenAI => builder.AddAzureOpenAIClient(connectionName).AddChatClient(connectionInfo.SelectedModel),
-            ClientChatProvider.AzureAIInference => builder.AddAzureInferenceClient(connectionName, connectionInfo),
            _ => throw new NotSupportedException($"Unsupported provider: {connectionInfo.Provider}")
        };

@@ -44,16 +41,6 @@ public static class ChatClientExtensions
        })
        .AddChatClient(connectionInfo.SelectedModel);

-    private static ChatClientBuilder AddAzureInferenceClient(this IHostApplicationBuilder builder, string connectionName, ChatClientConnectionInfo connectionInfo) =>
-        builder.Services.AddChatClient(sp =>
-        {
-            var credential = new AzureKeyCredential(connectionInfo.AccessKey!);
-
-            var client = new ChatCompletionsClient(connectionInfo.Endpoint, credential, new AzureAIInferenceClientOptions());
-
-            return client.AsIChatClient(connectionInfo.SelectedModel);
-        });
-
    private static ChatClientBuilder AddOllamaClient(this IHostApplicationBuilder builder, string connectionName, ChatClientConnectionInfo connectionInfo)
    {
        var httpKey = $"{connectionName}_http";
@@ -83,7 +70,6 @@ public static class ChatClientExtensions
            ClientChatProvider.Ollama => builder.AddKeyedOllamaClient(connectionName, connectionInfo),
            ClientChatProvider.OpenAI => builder.AddKeyedOpenAIClient(connectionName, connectionInfo),
            ClientChatProvider.AzureOpenAI => builder.AddKeyedAzureOpenAIClient(connectionName).AddKeyedChatClient(connectionName, connectionInfo.SelectedModel),
-            ClientChatProvider.AzureAIInference => builder.AddKeyedAzureInferenceClient(connectionName, connectionInfo),
            _ => throw new NotSupportedException($"Unsupported provider: {connectionInfo.Provider}")
        };

@@ -103,16 +89,6 @@ public static class ChatClientExtensions
        })
        .AddKeyedChatClient(connectionName, connectionInfo.SelectedModel);

-    private static ChatClientBuilder AddKeyedAzureInferenceClient(this IHostApplicationBuilder builder, string connectionName, ChatClientConnectionInfo connectionInfo) =>
-        builder.Services.AddKeyedChatClient(connectionName, sp =>
-        {
-            var credential = new AzureKeyCredential(connectionInfo.AccessKey!);
-
-            var client = new ChatCompletionsClient(connectionInfo.Endpoint, credential, new AzureAIInferenceClientOptions());
-
-            return client.AsIChatClient(connectionInfo.SelectedModel);
-        });
-
    private static ChatClientBuilder AddKeyedOllamaClient(this IHostApplicationBuilder builder, string connectionName, ChatClientConnectionInfo connectionInfo)
    {
        var httpKey = $"{connectionName}_http";
@@ -27,7 +27,7 @@ internal sealed class OpenAIResponsesAgentClient(HttpClient httpClient) : AgentC
            Transport = new HttpClientPipelineTransport(httpClient)
        };

-        var openAiClient = new OpenAIResponseClient(model: agentName, credential: new ApiKeyCredential("dummy-key"), options: options).AsIChatClient();
+        var openAiClient = new ResponsesClient(model: agentName, credential: new ApiKeyCredential("dummy-key"), options: options).AsIChatClient();
        var chatOptions = new ChatOptions()
        {
            ConversationId = threadId
@@ -32,6 +32,6 @@ AIAgent agent = client.GetChatClient(deploymentName).CreateAIAgent(JokerInstruct
 using IHost app = FunctionsApplication
    .CreateBuilder(args)
    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
+    .ConfigureDurableAgents(options => options.AddAIAgent(agent, timeToLive: TimeSpan.FromHours(1)))
    .Build();
 app.Run();
@@ -13,7 +13,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
     .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

 // Invoke the agent and output the text result.
@@ -45,7 +45,7 @@ namespace SampleApp
            }

            // Clone the input messages and turn them into response messages with upper case text.
-            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.DisplayName).ToList();
+            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();

            // Notify the thread of the input and output messages.
            await typedThread.MessageStore.AddMessagesAsync(messages.Concat(responseMessages), cancellationToken);
@@ -69,7 +69,7 @@ namespace SampleApp
            }

            // Clone the input messages and turn them into response messages with upper case text.
-            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.DisplayName).ToList();
+            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();

            // Notify the thread of the input and output messages.
            await typedThread.MessageStore.AddMessagesAsync(messages.Concat(responseMessages), cancellationToken);
@@ -79,7 +79,7 @@ namespace SampleApp
                yield return new AgentRunResponseUpdate
                {
                    AgentId = this.Id,
-                    AuthorName = this.DisplayName,
+                    AuthorName = message.AuthorName,
                    Role = ChatRole.Assistant,
                    Contents = message.Contents,
                    ResponseId = Guid.NewGuid().ToString("N"),
@@ -88,7 +88,7 @@ namespace SampleApp
            }
        }

-        private static IEnumerable<ChatMessage> CloneAndToUpperCase(IEnumerable<ChatMessage> messages, string agentName) => messages.Select(x =>
+        private static IEnumerable<ChatMessage> CloneAndToUpperCase(IEnumerable<ChatMessage> messages, string? agentName) => messages.Select(x =>
            {
                // Clone the message and update its author to be the agent.
                var messageClone = x.Clone();
@@ -11,7 +11,7 @@ var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";

 AIAgent agent = new OpenAIClient(
    apiKey)
-     .GetOpenAIResponseClient(model)
+     .GetResponsesClient(model)
     .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

 // Invoke the agent and output the text result.
@@ -11,11 +11,11 @@ var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new I
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-5";

 var client = new OpenAIClient(apiKey)
-        .GetOpenAIResponseClient(model)
+        .GetResponsesClient(model)
        .AsIChatClient().AsBuilder()
        .ConfigureOptions(o =>
        {
-            o.RawRepresentationFactory = _ => new ResponseCreationOptions()
+            o.RawRepresentationFactory = _ => new CreateResponseOptions()
            {
                ReasoningOptions = new()
                {
@@ -16,13 +16,13 @@ public class OpenAIResponseClientAgent : DelegatingAIAgent
    /// <summary>
    /// Initialize an instance of <see cref="OpenAIResponseClientAgent"/>.
    /// </summary>
-    /// <param name="client">Instance of <see cref="OpenAIResponseClient"/></param>
+    /// <param name="client">Instance of <see cref="ResponsesClient"/></param>
    /// <param name="instructions">Optional instructions for the agent.</param>
    /// <param name="name">Optional name for the agent.</param>
    /// <param name="description">Optional description for the agent.</param>
    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
    public OpenAIResponseClientAgent(
-        OpenAIResponseClient client,
+        ResponsesClient client,
        string? instructions = null,
        string? name = null,
        string? description = null,
@@ -39,11 +39,11 @@ public class OpenAIResponseClientAgent : DelegatingAIAgent
    /// <summary>
    /// Initialize an instance of <see cref="OpenAIResponseClientAgent"/>.
    /// </summary>
-    /// <param name="client">Instance of <see cref="OpenAIResponseClient"/></param>
+    /// <param name="client">Instance of <see cref="ResponsesClient"/></param>
    /// <param name="options">Options to create the agent.</param>
    /// <param name="loggerFactory">Optional instance of <see cref="ILoggerFactory"/></param>
    public OpenAIResponseClientAgent(
-        OpenAIResponseClient client, ChatClientAgentOptions options, ILoggerFactory? loggerFactory = null) :
+        ResponsesClient client, ChatClientAgentOptions options, ILoggerFactory? loggerFactory = null) :
        base(new ChatClientAgent((client ?? throw new ArgumentNullException(nameof(client))).AsIChatClient(), options, loggerFactory))
    {
    }
@@ -55,8 +55,8 @@ public class OpenAIResponseClientAgent : DelegatingAIAgent
    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
    /// <param name="options">Optional parameters for agent invocation.</param>
    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A <see cref="OpenAIResponse"/> containing the list of <see cref="ChatMessage"/> items.</returns>
-    public virtual async Task<OpenAIResponse> RunAsync(
+    /// <returns>A <see cref="ResponseResult"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    public virtual async Task<ResponseResult> RunAsync(
        IEnumerable<ResponseItem> messages,
        AgentThread? thread = null,
        AgentRunOptions? options = null,
@@ -74,7 +74,7 @@ public class OpenAIResponseClientAgent : DelegatingAIAgent
    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
    /// <param name="options">Optional parameters for agent invocation.</param>
    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A <see cref="OpenAIResponse"/> containing the list of <see cref="ChatMessage"/> items.</returns>
+    /// <returns>A <see cref="ResponseResult"/> containing the list of <see cref="ChatMessage"/> items.</returns>
    public virtual async IAsyncEnumerable<StreamingResponseUpdate> RunStreamingAsync(
        IEnumerable<ResponseItem> messages,
        AgentThread? thread = null,
@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.

-// This sample demonstrates how to create OpenAIResponseClientAgent directly from an OpenAIResponseClient instance.
+// This sample demonstrates how to create OpenAIResponseClientAgent directly from an ResponsesClient instance.

 using OpenAI;
 using OpenAI.Responses;
@@ -9,16 +9,16 @@ using OpenAIResponseClientSample;
 var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
 var model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-mini";

-// Create an OpenAIResponseClient directly from OpenAIClient
-OpenAIResponseClient responseClient = new OpenAIClient(apiKey).GetOpenAIResponseClient(model);
+// Create a ResponsesClient directly from OpenAIClient
+ResponsesClient responseClient = new OpenAIClient(apiKey).GetResponsesClient(model);

-// Create an agent directly from the OpenAIResponseClient using OpenAIResponseClientAgent
+// Create an agent directly from the ResponsesClient using OpenAIResponseClientAgent
 OpenAIResponseClientAgent agent = new(responseClient, instructions: "You are good at telling jokes.", name: "Joker");

 ResponseItem userMessage = ResponseItem.CreateUserMessageItem("Tell me a joke about a pirate.");

 // Invoke the agent and output the text result.
-OpenAIResponse response = await agent.RunAsync([userMessage]);
+ResponseResult response = await agent.RunAsync([userMessage]);
 Console.WriteLine(response.GetOutputText());

 // Invoke the agent with streaming support.
@@ -21,8 +21,8 @@ string model = Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-4o-min
 OpenAIClient openAIClient = new(apiKey);
 ConversationClient conversationClient = openAIClient.GetConversationClient();

-// Create an agent directly from the OpenAIResponseClient using OpenAIResponseClientAgent
-ChatClientAgent agent = new(openAIClient.GetOpenAIResponseClient(model).AsIChatClient(), instructions: "You are a helpful assistant.", name: "ConversationAgent");
+// Create an agent directly from the ResponsesClient using OpenAIResponseClientAgent
+ChatClientAgent agent = new(openAIClient.GetResponsesClient(model).AsIChatClient(), instructions: "You are a helpful assistant.", name: "ConversationAgent");

 ClientResult createConversationResult = await conversationClient.CreateConversationAsync(BinaryContent.Create(BinaryData.FromString("{}")));

@@ -22,7 +22,7 @@ var stateStore = new Dictionary<string, JsonElement?>();
 AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
     .CreateAIAgent(
        name: "SpaceNovelWriter",
        instructions: "You are a space novel writer. Always research relevant facts and generate character profiles for the main characters before writing novels." +
@@ -13,7 +13,7 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
     .CreateAIAgent();

 // Enable background responses (only supported by OpenAI Responses at this time).
@@ -73,7 +73,7 @@ internal sealed class Program
        Dictionary<string, byte[]> screenshots = ComputerUseUtil.LoadScreenshotAssets();

        ChatOptions chatOptions = new();
-        ResponseCreationOptions responseCreationOptions = new()
+        CreateResponseOptions responseCreationOptions = new()
        {
            TruncationMode = ResponseTruncationMode.Auto
        };
@@ -30,7 +30,7 @@ var mcpTool = new HostedMcpServerTool(
 AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
-     .GetOpenAIResponseClient(deploymentName)
+     .GetResponsesClient(deploymentName)
     .CreateAIAgent(
        instructions: "You answer questions by searching the Microsoft Learn content only.",
        name: "MicrosoftLearnAgent",
@@ -57,7 +57,7 @@ var mcpToolWithApproval = new HostedMcpServerTool(
 AIAgent agentWithRequiredApproval = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
-    .GetOpenAIResponseClient(deploymentName)
+    .GetResponsesClient(deploymentName)
    .CreateAIAgent(
        instructions: "You answer questions by searching the Microsoft Learn content only.",
        name: "MicrosoftLearnAgentWithApproval",
@@ -35,7 +35,7 @@
  </ItemGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.4" />
+    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.5" />
    <PackageReference Include="Azure.AI.OpenAI" Version="2.7.0-beta.2" />
    <PackageReference Include="Azure.Identity" Version="1.17.1" />
    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.251125.1" />
@@ -35,7 +35,7 @@
  </ItemGroup>

  <ItemGroup>
-    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.4" />
+    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.5" />
    <PackageReference Include="Azure.AI.OpenAI" Version="2.7.0-beta.2" />
    <PackageReference Include="Azure.Identity" Version="1.17.1" />
    <PackageReference Include="Microsoft.Agents.AI.Workflows" Version="1.0.0-preview.251125.1" />
@@ -27,7 +27,7 @@ TokenCredential browserCredential = new InteractiveBrowserCredential(
 using IChatClient client = new AzureOpenAIClient(
    new Uri(endpoint),
    new AzureCliCredential())
-    .GetOpenAIResponseClient(deploymentName)
+    .GetResponsesClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .WithPurview(browserCredential, new PurviewSettings("Agent Framework Test App"))
@@ -30,7 +30,6 @@ internal sealed class A2AAgent : AIAgent
    private readonly string? _id;
    private readonly string? _name;
    private readonly string? _description;
-    private readonly string? _displayName;
    private readonly ILogger _logger;

    /// <summary>
@@ -40,9 +39,8 @@ internal sealed class A2AAgent : AIAgent
    /// <param name="id">The unique identifier for the agent.</param>
    /// <param name="name">The the name of the agent.</param>
    /// <param name="description">The description of the agent.</param>
-    /// <param name="displayName">The display name of the agent.</param>
    /// <param name="loggerFactory">Optional logger factory to use for logging.</param>
-    public A2AAgent(A2AClient a2aClient, string? id = null, string? name = null, string? description = null, string? displayName = null, ILoggerFactory? loggerFactory = null)
+    public A2AAgent(A2AClient a2aClient, string? id = null, string? name = null, string? description = null, ILoggerFactory? loggerFactory = null)
    {
        _ = Throw.IfNull(a2aClient);

@@ -50,7 +48,6 @@ internal sealed class A2AAgent : AIAgent
        this._id = id;
        this._name = name;
        this._description = description;
-        this._displayName = displayName;
        this._logger = (loggerFactory ?? NullLoggerFactory.Instance).CreateLogger<A2AAgent>();
    }

@@ -203,9 +200,6 @@ internal sealed class A2AAgent : AIAgent
    /// <inheritdoc/>
    public override string? Name => this._name ?? base.Name;

-    /// <inheritdoc/>
-    public override string DisplayName => this._displayName ?? base.DisplayName;
-
    /// <inheritdoc/>
    public override string? Description => this._description ?? base.Description;

@@ -33,9 +33,8 @@ public static class A2AClientExtensions
    /// <param name="id">The unique identifier for the agent.</param>
    /// <param name="name">The the name of the agent.</param>
    /// <param name="description">The description of the agent.</param>
-    /// <param name="displayName">The display name of the agent.</param>
    /// <param name="loggerFactory">Optional logger factory for enabling logging within the agent.</param>
    /// <returns>An <see cref="AIAgent"/> instance backed by the A2A agent.</returns>
-    public static AIAgent GetAIAgent(this A2AClient client, string? id = null, string? name = null, string? description = null, string? displayName = null, ILoggerFactory? loggerFactory = null) =>
-        new A2AAgent(client, id, name, description, displayName, loggerFactory);
+    public static AIAgent GetAIAgent(this A2AClient client, string? id = null, string? name = null, string? description = null, ILoggerFactory? loggerFactory = null) =>
+        new A2AAgent(client, id, name, description, loggerFactory);
 }
@@ -60,18 +60,6 @@ public abstract class AIAgent
    /// </remarks>
    public virtual string? Name { get; }

-    /// <summary>
-    /// Gets a display-friendly name for the agent.
-    /// </summary>
-    /// <value>
-    /// The agent's <see cref="Name"/> if available, otherwise the <see cref="Id"/>.
-    /// </value>
-    /// <remarks>
-    /// This property provides a guaranteed non-null string suitable for display in user interfaces,
-    /// logs, or other contexts where a readable identifier is needed.
-    /// </remarks>
-    public virtual string DisplayName => this.Name ?? this.Id;
-
    /// <summary>
    /// Gets a description of the agent's purpose, capabilities, or behavior.
    /// </summary>
@@ -25,7 +25,7 @@ namespace Microsoft.Agents.AI;
 /// Derived classes can override specific methods to add custom behavior while maintaining compatibility with the agent interface.
 /// </para>
 /// </remarks>
-public class DelegatingAIAgent : AIAgent
+public abstract class DelegatingAIAgent : AIAgent
 {
    /// <summary>
    /// Initializes a new instance of the <see cref="DelegatingAIAgent"/> class with the specified inner agent.
@@ -23,11 +23,6 @@ internal sealed class AzureAIProjectChatClient : DelegatingChatClient
    private readonly AgentRecord? _agentRecord;
    private readonly ChatOptions? _chatOptions;
    private readonly AgentReference _agentReference;
-    /// <summary>
-    /// The usage of a no-op model is a necessary change to avoid OpenAIClients to throw exceptions when
-    /// used with Azure AI Agents as the model used is now defined at the agent creation time.
-    /// </summary>
-    private const string NoOpModel = "no-op";

    /// <summary>
    /// Initializes a new instance of the <see cref="AzureAIProjectChatClient"/> class.
@@ -42,7 +37,7 @@ internal sealed class AzureAIProjectChatClient : DelegatingChatClient
    internal AzureAIProjectChatClient(AIProjectClient aiProjectClient, AgentReference agentReference, string? defaultModelId, ChatOptions? chatOptions)
        : base(Throw.IfNull(aiProjectClient)
            .GetProjectOpenAIClient()
-            .GetOpenAIResponseClient(defaultModelId ?? NoOpModel)
+            .GetProjectResponsesClientForAgent(agentReference)
            .AsIChatClient())
    {
        this._agentClient = aiProjectClient;
@@ -132,13 +127,15 @@ internal sealed class AzureAIProjectChatClient : DelegatingChatClient

        agentEnabledChatOptions.RawRepresentationFactory = (client) =>
        {
-            if (originalFactory?.Invoke(this) is not ResponseCreationOptions responseCreationOptions)
+            if (originalFactory?.Invoke(this) is not CreateResponseOptions responseCreationOptions)
            {
-                responseCreationOptions = new ResponseCreationOptions();
+                responseCreationOptions = new CreateResponseOptions();
            }

-            ResponseCreationOptionsExtensions.set_Agent(responseCreationOptions, this._agentReference);
-            ResponseCreationOptionsExtensions.set_Model(responseCreationOptions, null);
+            responseCreationOptions.Agent = this._agentReference;
+#pragma warning disable SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+            responseCreationOptions.Patch.Remove("$.model"u8);
+#pragma warning restore SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

            return responseCreationOptions;
        };
@@ -400,7 +400,7 @@ public static partial class AzureAIProjectChatClientExtensions
        };

        // Attempt to capture breaking glass options from the raw representation factory that match the agent definition.
-        if (options.ChatOptions?.RawRepresentationFactory?.Invoke(new NoOpChatClient()) is ResponseCreationOptions respCreationOptions)
+        if (options.ChatOptions?.RawRepresentationFactory?.Invoke(new NoOpChatClient()) is CreateResponseOptions respCreationOptions)
        {
            agentDefinition.ReasoningOptions = respCreationOptions.ReasoningOptions;
        }
@@ -466,7 +466,7 @@ public static partial class AzureAIProjectChatClientExtensions
        };

        // Attempt to capture breaking glass options from the raw representation factory that match the agent definition.
-        if (options.ChatOptions?.RawRepresentationFactory?.Invoke(new NoOpChatClient()) is ResponseCreationOptions respCreationOptions)
+        if (options.ChatOptions?.RawRepresentationFactory?.Invoke(new NoOpChatClient()) is CreateResponseOptions respCreationOptions)
        {
            agentDefinition.ReasoningOptions = respCreationOptions.ReasoningOptions;
        }
@@ -217,9 +217,7 @@ public class CosmosCheckpointStore<T> : JsonCheckpointStore, IDisposable
        }
    }

-    /// <summary>
-    /// Represents a checkpoint document stored in Cosmos DB.
-    /// </summary>
+    /// <summary>Represents a checkpoint document stored in Cosmos DB.</summary>
    internal sealed class CosmosCheckpointDocument
    {
        [JsonProperty("id")]
@@ -231,7 +231,7 @@ internal static class EntitiesApiExtensions
        return new EntityInfo(
            Id: entityId,
            Type: "agent",
-            Name: agent.DisplayName,
+            Name: agent.Name ?? agent.Id,
            Description: agent.Description,
            Framework: "agent_framework",
            Tools: tools,
@@ -16,29 +16,34 @@ internal class AgentEntity(IServiceProvider services, CancellationToken cancella
    private readonly DurableTaskClient _client = services.GetRequiredService<DurableTaskClient>();
    private readonly ILoggerFactory _loggerFactory = services.GetRequiredService<ILoggerFactory>();
    private readonly IAgentResponseHandler? _messageHandler = services.GetService<IAgentResponseHandler>();
+    private readonly DurableAgentsOptions _options = services.GetRequiredService<DurableAgentsOptions>();
    private readonly CancellationToken _cancellationToken = cancellationToken != default
        ? cancellationToken
        : services.GetService<IHostApplicationLifetime>()?.ApplicationStopping ?? CancellationToken.None;

-    public async Task<AgentRunResponse> RunAgentAsync(RunRequest request)
+    public Task<AgentRunResponse> RunAgentAsync(RunRequest request)
+    {
+        return this.Run(request);
+    }
+
+    // IDE1006 and VSTHRD200 disabled to allow method name to match the common cross-platform entity operation name.
+#pragma warning disable IDE1006
+#pragma warning disable VSTHRD200
+    public async Task<AgentRunResponse> Run(RunRequest request)
+#pragma warning restore VSTHRD200
+#pragma warning restore IDE1006
    {
        AgentSessionId sessionId = this.Context.Id;
-        IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> agents =
-            this._services.GetRequiredService<IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>>>();
-        if (!agents.TryGetValue(sessionId.Name, out Func<IServiceProvider, AIAgent>? agentFactory))
-        {
-            throw new InvalidOperationException($"Agent '{sessionId.Name}' not found");
-        }
-
-        AIAgent agent = agentFactory(this._services);
+        AIAgent agent = this.GetAgent(sessionId);
        EntityAgentWrapper agentWrapper = new(agent, this.Context, request, this._services);

        // Logger category is Microsoft.DurableTask.Agents.{agentName}.{sessionId}
-        ILogger logger = this._loggerFactory.CreateLogger($"Microsoft.DurableTask.Agents.{agent.Name}.{sessionId.Key}");
+        ILogger logger = this.GetLogger(agent.Name!, sessionId.Key);

        if (request.Messages.Count == 0)
        {
            logger.LogInformation("Ignoring empty request");
+            return new AgentRunResponse();
        }

        this.State.Data.ConversationHistory.Add(DurableAgentStateRequest.FromRunRequest(request));
@@ -113,6 +118,36 @@ internal class AgentEntity(IServiceProvider services, CancellationToken cancella
                    response.Usage?.TotalTokenCount);
            }

+            // Update TTL expiration time. Only schedule deletion check on first interaction.
+            // Subsequent interactions just update the expiration time; CheckAndDeleteIfExpiredAsync
+            // will reschedule the deletion check when it runs.
+            TimeSpan? timeToLive = this._options.GetTimeToLive(sessionId.Name);
+            if (timeToLive.HasValue)
+            {
+                DateTime newExpirationTime = DateTime.UtcNow.Add(timeToLive.Value);
+                bool isFirstInteraction = this.State.Data.ExpirationTimeUtc is null;
+
+                this.State.Data.ExpirationTimeUtc = newExpirationTime;
+                logger.LogTTLExpirationTimeUpdated(sessionId, newExpirationTime);
+
+                // Only schedule deletion check on the first interaction when entity is created.
+                // On subsequent interactions, we just update the expiration time. The scheduled
+                // CheckAndDeleteIfExpiredAsync will reschedule itself if the entity hasn't expired.
+                if (isFirstInteraction)
+                {
+                    this.ScheduleDeletionCheck(sessionId, logger, timeToLive.Value);
+                }
+            }
+            else
+            {
+                // TTL is disabled. Clear the expiration time if it was previously set.
+                if (this.State.Data.ExpirationTimeUtc.HasValue)
+                {
+                    logger.LogTTLExpirationTimeCleared(sessionId);
+                    this.State.Data.ExpirationTimeUtc = null;
+                }
+            }
+
            return response;
        }
        finally
@@ -121,4 +156,78 @@ internal class AgentEntity(IServiceProvider services, CancellationToken cancella
            DurableAgentContext.ClearCurrent();
        }
    }
+
+    /// <summary>
+    /// Checks if the entity has expired and deletes it if so, otherwise reschedules the deletion check.
+    /// </summary>
+    /// <remarks>
+    /// This method is called by the durable task runtime when a <c>CheckAndDeleteIfExpired</c> signal is received.
+    /// </remarks>
+    public void CheckAndDeleteIfExpired()
+    {
+        AgentSessionId sessionId = this.Context.Id;
+        AIAgent agent = this.GetAgent(sessionId);
+        ILogger logger = this.GetLogger(agent.Name!, sessionId.Key);
+
+        DateTime currentTime = DateTime.UtcNow;
+        DateTime? expirationTime = this.State.Data.ExpirationTimeUtc;
+
+        logger.LogTTLDeletionCheck(sessionId, expirationTime, currentTime);
+
+        if (expirationTime.HasValue)
+        {
+            if (currentTime >= expirationTime.Value)
+            {
+                // Entity has expired, delete it
+                logger.LogTTLEntityExpired(sessionId, expirationTime.Value);
+                this.State = null!;
+            }
+            else
+            {
+                // Entity hasn't expired yet, reschedule the deletion check
+                TimeSpan? timeToLive = this._options.GetTimeToLive(sessionId.Name);
+                if (timeToLive.HasValue)
+                {
+                    this.ScheduleDeletionCheck(sessionId, logger, timeToLive.Value);
+                }
+            }
+        }
+    }
+
+    private void ScheduleDeletionCheck(AgentSessionId sessionId, ILogger logger, TimeSpan timeToLive)
+    {
+        DateTime currentTime = DateTime.UtcNow;
+        DateTime expirationTime = this.State.Data.ExpirationTimeUtc ?? currentTime.Add(timeToLive);
+        TimeSpan minimumDelay = this._options.MinimumTimeToLiveSignalDelay;
+
+        // To avoid excessive scheduling, we schedule the deletion check for no less than the minimum delay.
+        DateTime scheduledTime = expirationTime > currentTime.Add(minimumDelay)
+            ? expirationTime
+            : currentTime.Add(minimumDelay);
+
+        logger.LogTTLDeletionScheduled(sessionId, scheduledTime);
+
+        // Schedule a signal to self to check for expiration
+        this.Context.SignalEntity(
+            this.Context.Id,
+            nameof(CheckAndDeleteIfExpired), // self-signal
+            options: new SignalEntityOptions { SignalTime = scheduledTime });
+    }
+
+    private AIAgent GetAgent(AgentSessionId sessionId)
+    {
+        IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> agents =
+            this._services.GetRequiredService<IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>>>();
+        if (!agents.TryGetValue(sessionId.Name, out Func<IServiceProvider, AIAgent>? agentFactory))
+        {
+            throw new InvalidOperationException($"Agent '{sessionId.Name}' not found");
+        }
+
+        return agentFactory(this._services);
+    }
+
+    private ILogger GetLogger(string agentName, string sessionKey)
+    {
+        return this._loggerFactory.CreateLogger($"Microsoft.DurableTask.Agents.{agentName}.{sessionKey}");
+    }
 }
@@ -1,5 +1,12 @@
 # Release History

+## [Unreleased]
+
+### Changed
+
+- Added TTL configuration for durable agent entities ([#2679](https://github.com/microsoft/agent-framework/pull/2679))
+- Switch to new "Run" method name ([#2843](https://github.com/microsoft/agent-framework/pull/2843))
+
 ## v1.0.0-preview.251204.1

 - Added orchestration ID to durable agent entity state ([#2137](https://github.com/microsoft/agent-framework/pull/2137))
@@ -22,7 +22,7 @@ internal class DefaultDurableAgentClient(DurableTaskClient client, ILoggerFactor

        await this._client.Entities.SignalEntityAsync(
            sessionId,
-            nameof(AgentEntity.RunAgentAsync),
+            nameof(AgentEntity.Run),
            request,
            cancellation: cancellationToken);

@@ -107,7 +107,7 @@ public sealed class DurableAIAgent : AIAgent
        {
            return await this._context.Entities.CallEntityAsync<AgentRunResponse>(
                durableThread.SessionId,
-                nameof(AgentEntity.RunAgentAsync),
+                nameof(AgentEntity.Run),
                request);
        }
        catch (EntityOperationFailedException e) when (e.FailureDetails.ErrorType == "EntityTaskNotFound")
@@ -9,23 +9,67 @@ public sealed class DurableAgentsOptions
 {
    // Agent names are case-insensitive
    private readonly Dictionary<string, Func<IServiceProvider, AIAgent>> _agentFactories = new(StringComparer.OrdinalIgnoreCase);
+    private readonly Dictionary<string, TimeSpan?> _agentTimeToLive = new(StringComparer.OrdinalIgnoreCase);

    internal DurableAgentsOptions()
    {
    }

+    /// <summary>
+    /// Gets or sets the default time-to-live (TTL) for agent entities.
+    /// </summary>
+    /// <remarks>
+    /// If an agent entity is idle for this duration, it will be automatically deleted.
+    /// Defaults to 14 days. Set to <see langword="null"/> to disable TTL for agents without explicit TTL configuration.
+    /// </remarks>
+    public TimeSpan? DefaultTimeToLive { get; set; } = TimeSpan.FromDays(14);
+
+    /// <summary>
+    /// Gets or sets the minimum delay for scheduling TTL deletion signals. Defaults to 5 minutes.
+    /// </summary>
+    /// <remarks>
+    /// This property is primarily useful for testing (where shorter delays are needed) or for
+    /// shorter-lived agents in workflows that need more rapid cleanup. The maximum allowed value is 5 minutes.
+    /// Reducing the minimum deletion delay below 5 minutes can be useful for testing or for ensuring rapid cleanup of short-lived agent sessions.
+    /// However, this can also increase the load on the system and should be used with caution.
+    /// </remarks>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when the value exceeds 5 minutes.</exception>
+    public TimeSpan MinimumTimeToLiveSignalDelay
+    {
+        get;
+        set
+        {
+            const int MaximumDelayMinutes = 5;
+            if (value > TimeSpan.FromMinutes(MaximumDelayMinutes))
+            {
+                throw new ArgumentOutOfRangeException(
+                    nameof(value),
+                    value,
+                    $"The minimum time-to-live signal delay cannot exceed {MaximumDelayMinutes} minutes.");
+            }
+
+            field = value;
+        }
+    } = TimeSpan.FromMinutes(5);
+
    /// <summary>
    /// Adds an AI agent factory to the options.
    /// </summary>
    /// <param name="name">The name of the agent.</param>
    /// <param name="factory">The factory function to create the agent.</param>
+    /// <param name="timeToLive">Optional time-to-live for this agent's entities. If not specified, uses <see cref="DefaultTimeToLive"/>.</param>
    /// <returns>The options instance.</returns>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> or <paramref name="factory"/> is null.</exception>
-    public DurableAgentsOptions AddAIAgentFactory(string name, Func<IServiceProvider, AIAgent> factory)
+    public DurableAgentsOptions AddAIAgentFactory(string name, Func<IServiceProvider, AIAgent> factory, TimeSpan? timeToLive = null)
    {
        ArgumentNullException.ThrowIfNull(name);
        ArgumentNullException.ThrowIfNull(factory);
        this._agentFactories.Add(name, factory);
+        if (timeToLive.HasValue)
+        {
+            this._agentTimeToLive[name] = timeToLive;
+        }
+
        return this;
    }

@@ -50,12 +94,13 @@ public sealed class DurableAgentsOptions
    /// Adds an AI agent to the options.
    /// </summary>
    /// <param name="agent">The agent to add.</param>
+    /// <param name="timeToLive">Optional time-to-live for this agent's entities. If not specified, uses <see cref="DefaultTimeToLive"/>.</param>
    /// <returns>The options instance.</returns>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="agent"/> is null.</exception>
    /// <exception cref="ArgumentException">
    /// Thrown when <paramref name="agent.Name"/> is null or whitespace or when an agent with the same name has already been registered.
    /// </exception>
-    public DurableAgentsOptions AddAIAgent(AIAgent agent)
+    public DurableAgentsOptions AddAIAgent(AIAgent agent, TimeSpan? timeToLive = null)
    {
        ArgumentNullException.ThrowIfNull(agent);

@@ -70,6 +115,11 @@ public sealed class DurableAgentsOptions
        }

        this._agentFactories.Add(agent.Name, sp => agent);
+        if (timeToLive.HasValue)
+        {
+            this._agentTimeToLive[agent.Name] = timeToLive;
+        }
+
        return this;
    }

@@ -81,4 +131,14 @@ public sealed class DurableAgentsOptions
    {
        return this._agentFactories.AsReadOnly();
    }
+
+    /// <summary>
+    /// Gets the time-to-live for a specific agent, or the default TTL if not specified.
+    /// </summary>
+    /// <param name="agentName">The name of the agent.</param>
+    /// <returns>The time-to-live for the agent, or the default TTL if not specified.</returns>
+    internal TimeSpan? GetTimeToLive(string agentName)
+    {
+        return this._agentTimeToLive.TryGetValue(agentName, out TimeSpan? ttl) ? ttl : this.DefaultTimeToLive;
+    }
 }
@@ -46,4 +46,58 @@ internal static partial class Logs
        Level = LogLevel.Information,
        Message = "Found response for agent with session ID '{SessionId}' with correlation ID '{CorrelationId}'")]
    public static partial void LogDonePollingForResponse(this ILogger logger, AgentSessionId sessionId, string correlationId);
+
+    [LoggerMessage(
+        EventId = 6,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL expiration time updated to {ExpirationTime:O}")]
+    public static partial void LogTTLExpirationTimeUpdated(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime expirationTime);
+
+    [LoggerMessage(
+        EventId = 7,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL deletion signal scheduled for {ScheduledTime:O}")]
+    public static partial void LogTTLDeletionScheduled(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime scheduledTime);
+
+    [LoggerMessage(
+        EventId = 8,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL deletion check running. Expiration time: {ExpirationTime:O}, Current time: {CurrentTime:O}")]
+    public static partial void LogTTLDeletionCheck(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime? expirationTime,
+        DateTime currentTime);
+
+    [LoggerMessage(
+        EventId = 9,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] Entity expired and deleted due to TTL. Expiration time: {ExpirationTime:O}")]
+    public static partial void LogTTLEntityExpired(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime expirationTime);
+
+    [LoggerMessage(
+        EventId = 10,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL deletion signal rescheduled for {ScheduledTime:O}")]
+    public static partial void LogTTLRescheduled(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime scheduledTime);
+
+    [LoggerMessage(
+        EventId = 11,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL expiration time cleared (TTL disabled)")]
+    public static partial void LogTTLExpirationTimeCleared(
+        this ILogger logger,
+        AgentSessionId sessionId);
 }
@@ -85,6 +85,9 @@ public static class ServiceCollectionExtensions
        // The agent dictionary contains the real agent factories, which is used by the agent entities.
        services.AddSingleton(agents);

+        // Register the options so AgentEntity can access TTL configuration
+        services.AddSingleton(options);
+
        // The keyed services are used to resolve durable agent *proxy* instances for external clients.
        foreach (var factory in agents)
        {
@@ -17,6 +17,13 @@ internal sealed class DurableAgentStateData
    [JsonPropertyName("conversationHistory")]
    public IList<DurableAgentStateEntry> ConversationHistory { get; init; } = [];

+    /// <summary>
+    /// Gets or sets the expiration time (UTC) for this agent entity.
+    /// If the entity is idle beyond this time, it will be automatically deleted.
+    /// </summary>
+    [JsonPropertyName("expirationTimeUtc")]
+    public DateTime? ExpirationTimeUtc { get; set; }
+
    /// <summary>
    /// Gets any additional data found during deserialization that does not map to known properties.
    /// </summary>
@@ -61,7 +61,7 @@ public static partial class MicrosoftAgentAIHostingOpenAIEndpointRouteBuilderExt

        path ??= $"/{agent.Name}/v1/chat/completions";
        var group = endpoints.MapGroup(path);
-        var endpointAgentName = agent.DisplayName;
+        var endpointAgentName = agent.Name ?? agent.Id;

        group.MapPost("/", async ([FromBody] CreateChatCompletion request, CancellationToken cancellationToken)
            => await AIAgentChatCompletionsProcessor.CreateChatCompletionAsync(agent, request, cancellationToken).ConfigureAwait(false))
@@ -76,7 +76,7 @@ public static partial class MicrosoftAgentAIHostingOpenAIEndpointRouteBuilderExt
        var handlers = new ResponsesHttpHandler(responsesService);

        var group = endpoints.MapGroup(responsesPath);
-        var endpointAgentName = agent.DisplayName;
+        var endpointAgentName = agent.Name ?? agent.Id;

        // Create response endpoint
        group.MapPost("/", handlers.CreateResponseAsync)
@@ -84,22 +84,18 @@ internal sealed class ConversationReferenceJsonConverter : JsonConverter<Convers
            return;
        }

-        // If only ID is present and no metadata, serialize as a simple string
-        if (value.Metadata is null || value.Metadata.Count == 0)
+        // Ideally if only ID is present and no metadata, we would serialize as a simple string.
+        // However, while a request's "conversation" property can be either a string or an object
+        // containing a string, a response's "conversation" property is always an object. Since
+        // here we don't know which scenario we're in, we always serialize as an object, which works
+        // in any scenario.
+        writer.WriteStartObject();
+        writer.WriteString("id", value.Id);
+        if (value.Metadata is not null)
        {
-            writer.WriteStringValue(value.Id);
-        }
-        else
-        {
-            // Otherwise, serialize as an object
-            writer.WriteStartObject();
-            writer.WriteString("id", value.Id);
-            if (value.Metadata is not null)
-            {
-                writer.WritePropertyName("metadata");
-                JsonSerializer.Serialize(writer, value.Metadata, OpenAIHostingJsonContext.Default.DictionaryStringString);
-            }
-            writer.WriteEndObject();
+            writer.WritePropertyName("metadata");
+            JsonSerializer.Serialize(writer, value.Metadata, OpenAIHostingJsonContext.Default.DictionaryStringString);
        }
+        writer.WriteEndObject();
    }
 }
@@ -73,22 +73,22 @@ public static class AIAgentWithOpenAIExtensions
    }

    /// <summary>
-    /// Runs the AI agent with a collection of OpenAI response items and returns the response as a native OpenAI <see cref="OpenAIResponse"/>.
+    /// Runs the AI agent with a collection of OpenAI response items and returns the response as a native OpenAI <see cref="ResponseResult"/>.
    /// </summary>
    /// <param name="agent">The AI agent to run.</param>
    /// <param name="messages">The collection of OpenAI response items to send to the agent.</param>
    /// <param name="thread">The conversation thread to continue with this invocation. If not provided, creates a new thread. The thread will be mutated with the provided messages and agent response.</param>
    /// <param name="options">Optional parameters for agent invocation.</param>
    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    /// <returns>A <see cref="Task{OpenAIResponse}"/> representing the asynchronous operation that returns a native OpenAI <see cref="OpenAIResponse"/> response.</returns>
+    /// <returns>A <see cref="Task{ResponseResult}"/> representing the asynchronous operation that returns a native OpenAI <see cref="ResponseResult"/> response.</returns>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="agent"/> or <paramref name="messages"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException">Thrown when the agent's response cannot be converted to an <see cref="OpenAIResponse"/>, typically when the underlying representation is not an OpenAI response.</exception>
+    /// <exception cref="ArgumentException">Thrown when the agent's response cannot be converted to an <see cref="ResponseResult"/>, typically when the underlying representation is not an OpenAI response.</exception>
    /// <exception cref="NotSupportedException">Thrown when any message in <paramref name="messages"/> has a type that is not supported by the message conversion method.</exception>
    /// <remarks>
    /// This method converts the OpenAI response items to the Microsoft Extensions AI format using the appropriate conversion method,
-    /// runs the agent with the converted message collection, and then extracts the native OpenAI <see cref="OpenAIResponse"/> from the response using <see cref="AgentRunResponseExtensions.AsOpenAIResponse"/>.
+    /// runs the agent with the converted message collection, and then extracts the native OpenAI <see cref="ResponseResult"/> from the response using <see cref="AgentRunResponseExtensions.AsOpenAIResponse"/>.
    /// </remarks>
-    public static async Task<OpenAIResponse> RunAsync(this AIAgent agent, IEnumerable<ResponseItem> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+    public static async Task<ResponseResult> RunAsync(this AIAgent agent, IEnumerable<ResponseItem> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
    {
        Throw.IfNull(agent);
        Throw.IfNull(messages);
@@ -29,17 +29,17 @@ public static class AgentRunResponseExtensions
    }

    /// <summary>
-    /// Creates or extracts a native OpenAI <see cref="OpenAIResponse"/> object from an <see cref="AgentRunResponse"/>.
+    /// Creates or extracts a native OpenAI <see cref="ResponseResult"/> object from an <see cref="AgentRunResponse"/>.
    /// </summary>
    /// <param name="response">The agent response.</param>
-    /// <returns>The OpenAI <see cref="OpenAIResponse"/> object.</returns>
+    /// <returns>The OpenAI <see cref="ResponseResult"/> object.</returns>
    /// <exception cref="ArgumentNullException"><paramref name="response"/> is <see langword="null"/>.</exception>
-    public static OpenAIResponse AsOpenAIResponse(this AgentRunResponse response)
+    public static ResponseResult AsOpenAIResponse(this AgentRunResponse response)
    {
        Throw.IfNull(response);

        return
-            response.RawRepresentation as OpenAIResponse ??
-            response.AsChatResponse().AsOpenAIResponse();
+            response.RawRepresentation as ResponseResult ??
+            response.AsChatResponse().AsOpenAIResponseResult();
    }
 }
@@ -8,7 +8,7 @@ using Microsoft.Shared.Diagnostics;
 namespace OpenAI.Responses;

 /// <summary>
-/// Provides extension methods for <see cref="OpenAIResponseClient"/>
+/// Provides extension methods for <see cref="ResponsesClient"/>
 /// to simplify the creation of AI agents that work with OpenAI services.
 /// </summary>
 /// <remarks>
@@ -20,9 +20,9 @@ namespace OpenAI.Responses;
 public static class OpenAIResponseClientExtensions
 {
    /// <summary>
-    /// Creates an AI agent from an <see cref="OpenAIResponseClient"/> using the OpenAI Response API.
+    /// Creates an AI agent from an <see cref="ResponsesClient"/> using the OpenAI Response API.
    /// </summary>
-    /// <param name="client">The <see cref="OpenAIResponseClient" /> to use for the agent.</param>
+    /// <param name="client">The <see cref="ResponsesClient" /> to use for the agent.</param>
    /// <param name="instructions">Optional system instructions that define the agent's behavior and personality.</param>
    /// <param name="name">Optional name for the agent for identification purposes.</param>
    /// <param name="description">Optional description of the agent's capabilities and purpose.</param>
@@ -33,7 +33,7 @@ public static class OpenAIResponseClientExtensions
    /// <returns>An <see cref="ChatClientAgent"/> instance backed by the OpenAI Response service.</returns>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="client"/> is <see langword="null"/>.</exception>
    public static ChatClientAgent CreateAIAgent(
-        this OpenAIResponseClient client,
+        this ResponsesClient client,
        string? instructions = null,
        string? name = null,
        string? description = null,
@@ -61,9 +61,9 @@ public static class OpenAIResponseClientExtensions
    }

    /// <summary>
-    /// Creates an AI agent from an <see cref="OpenAIResponseClient"/> using the OpenAI Response API.
+    /// Creates an AI agent from an <see cref="ResponsesClient"/> using the OpenAI Response API.
    /// </summary>
-    /// <param name="client">The <see cref="OpenAIResponseClient" /> to use for the agent.</param>
+    /// <param name="client">The <see cref="ResponsesClient" /> to use for the agent.</param>
    /// <param name="options">Full set of options to configure the agent.</param>
    /// <param name="clientFactory">Provides a way to customize the creation of the underlying <see cref="IChatClient"/> used by the agent.</param>
    /// <param name="loggerFactory">Optional logger factory for enabling logging within the agent.</param>
@@ -71,7 +71,7 @@ public static class OpenAIResponseClientExtensions
    /// <returns>An <see cref="ChatClientAgent"/> instance backed by the OpenAI Response service.</returns>
    /// <exception cref="ArgumentNullException">Thrown when <paramref name="client"/> or <paramref name="options"/> is <see langword="null"/>.</exception>
    public static ChatClientAgent CreateAIAgent(
-        this OpenAIResponseClient client,
+        this ResponsesClient client,
        ChatClientAgentOptions options,
        Func<IChatClient, IChatClient>? clientFactory = null,
        ILoggerFactory? loggerFactory = null,
@@ -111,7 +111,7 @@ public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential proj
        if (inputArguments is not null)
        {
            JsonNode jsonNode = ConvertDictionaryToJson(inputArguments);
-            ResponseCreationOptions responseCreationOptions = new();
+            CreateResponseOptions responseCreationOptions = new();
 #pragma warning disable SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
            responseCreationOptions.Patch.Set("$.structured_inputs"u8, BinaryData.FromString(jsonNode.ToJsonString()));
 #pragma warning restore SCME0001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
@@ -206,7 +206,7 @@ public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential proj
    public override async Task<ChatMessage> GetMessageAsync(string conversationId, string messageId, CancellationToken cancellationToken = default)
    {
        AgentResponseItem responseItem = await this.GetConversationClient().GetProjectConversationItemAsync(conversationId, messageId, include: null, cancellationToken).ConfigureAwait(false);
-        ResponseItem[] items = [responseItem.AsOpenAIResponseItem()];
+        ResponseItem[] items = [responseItem.AsResponseResultItem()];
        return items.AsChatMessages().Single();
    }

@@ -223,7 +223,7 @@ public sealed class AzureAgentProvider(Uri projectEndpoint, TokenCredential proj

        await foreach (AgentResponseItem responseItem in this.GetConversationClient().GetProjectConversationItemsAsync(conversationId, null, limit, order.ToString(), after, before, include: null, cancellationToken).ConfigureAwait(false))
        {
-            ResponseItem[] items = [responseItem.AsOpenAIResponseItem()];
+            ResponseItem[] items = [responseItem.AsResponseResultItem()];
            foreach (ChatMessage message in items.AsChatMessages())
            {
                yield return message;
@@ -11,7 +11,7 @@ namespace Microsoft.Agents.AI.Workflows;
 /// </summary>
 public sealed class DirectEdgeData : EdgeData
 {
-    internal DirectEdgeData(string sourceId, string sinkId, EdgeId id, PredicateT? condition = null) : base(id)
+    internal DirectEdgeData(string sourceId, string sinkId, EdgeId id, PredicateT? condition = null, string? label = null) : base(id, label)
    {
        this.SourceId = sourceId;
        this.SinkId = sinkId;
@@ -14,10 +14,16 @@ public abstract class EdgeData
    /// </summary>
    internal abstract EdgeConnection Connection { get; }

-    internal EdgeData(EdgeId id)
+    internal EdgeData(EdgeId id, string? label = null)
    {
        this.Id = id;
+        this.Label = label;
    }

    internal EdgeId Id { get; }
+
+    /// <summary>
+    /// An optional label for the edge, allowing for arbitrary metadata to be associated with it.
+    /// </summary>
+    public string? Label { get; }
 }
@@ -10,7 +10,7 @@ namespace Microsoft.Agents.AI.Workflows;
 /// </summary>
 internal sealed class FanInEdgeData : EdgeData
 {
-    internal FanInEdgeData(List<string> sourceIds, string sinkId, EdgeId id) : base(id)
+    internal FanInEdgeData(List<string> sourceIds, string sinkId, EdgeId id, string? label) : base(id, label)
    {
        this.SourceIds = sourceIds;
        this.SinkId = sinkId;
@@ -13,7 +13,7 @@ namespace Microsoft.Agents.AI.Workflows;
 /// </summary>
 internal sealed class FanOutEdgeData : EdgeData
 {
-    internal FanOutEdgeData(string sourceId, List<string> sinkIds, EdgeId edgeId, AssignerF? assigner = null) : base(edgeId)
+    internal FanOutEdgeData(string sourceId, List<string> sinkIds, EdgeId edgeId, AssignerF? assigner = null, string? label = null) : base(edgeId, label)
    {
        this.SourceId = sourceId;
        this.SinkIds = sinkIds;
@@ -125,14 +125,14 @@ public sealed class HandoffsWorkflowBuilder
            {
                Throw.ArgumentException(
                    nameof(to),
-                    $"The provided target agent '{to.DisplayName}' has no description, name, or instructions, and no handoff description has been provided. " +
+                    $"The provided target agent '{to.Name ?? to.Id}' has no description, name, or instructions, and no handoff description has been provided. " +
                    "At least one of these is required to register a handoff so that the appropriate target agent can be chosen.");
            }
        }

        if (!handoffs.Add(new(to, handoffReason)))
        {
-            Throw.InvalidOperationException($"A handoff from agent '{from.DisplayName}' to agent '{to.DisplayName}' has already been registered.");
+            Throw.InvalidOperationException($"A handoff from agent '{from.Name ?? from.Id}' to agent '{to.Name ?? to.Id}' has already been registered.");
        }

        return this;
@@ -20,7 +20,7 @@ internal sealed class AgentRunStreamingExecutor(AIAgent agent, bool includeInput

    protected override async ValueTask TakeTurnAsync(List<ChatMessage> messages, IWorkflowContext context, bool? emitEvents, CancellationToken cancellationToken = default)
    {
-        List<ChatMessage>? roleChanged = messages.ChangeAssistantToUserForOtherParticipants(agent.DisplayName);
+        List<ChatMessage>? roleChanged = messages.ChangeAssistantToUserForOtherParticipants(agent.Name ?? agent.Id);

        List<AgentRunResponseUpdate> updates = [];
        await foreach (var update in agent.RunStreamingAsync(messages, cancellationToken: cancellationToken).ConfigureAwait(false))
@@ -67,7 +67,7 @@ internal sealed class HandoffAgentExecutor(
            List<AgentRunResponseUpdate> updates = [];
            List<ChatMessage> allMessages = handoffState.Messages;

-            List<ChatMessage>? roleChanges = allMessages.ChangeAssistantToUserForOtherParticipants(this._agent.DisplayName);
+            List<ChatMessage>? roleChanges = allMessages.ChangeAssistantToUserForOtherParticipants(this._agent.Name ?? this._agent.Id);

            await foreach (var update in this._agent.RunStreamingAsync(allMessages,
                                                                       options: this._agentOptions,
@@ -85,7 +85,7 @@ internal sealed class HandoffAgentExecutor(
                                new AgentRunResponseUpdate
                                {
                                    AgentId = this._agent.Id,
-                                    AuthorName = this._agent.DisplayName,
+                                    AuthorName = this._agent.Name ?? this._agent.Id,
                                    Contents = [new FunctionResultContent(fcc.CallId, "Transferred.")],
                                    CreatedAt = DateTimeOffset.UtcNow,
                                    MessageId = Guid.NewGuid().ToString("N"),
@@ -99,10 +99,30 @@ public static class WorkflowVisualizer
        }

        // Emit normal edges
-        foreach (var (src, target, isConditional) in ComputeNormalEdges(workflow))
+        foreach (var (src, target, isConditional, label) in ComputeNormalEdges(workflow))
        {
-            var edgeAttr = isConditional ? " [style=dashed, label=\"conditional\"]" : "";
-            lines.Add($"{indent}\"{MapId(src)}\" -> \"{MapId(target)}\"{edgeAttr};");
+            // Build edge attributes
+            var attributes = new List<string>();
+
+            // Add style for conditional edges
+            if (isConditional)
+            {
+                attributes.Add("style=dashed");
+            }
+
+            // Add label (custom label or default "conditional" for conditional edges)
+            if (label != null)
+            {
+                attributes.Add($"label=\"{EscapeDotLabel(label)}\"");
+            }
+            else if (isConditional)
+            {
+                attributes.Add("label=\"conditional\"");
+            }
+
+            // Combine attributes
+            var attrString = attributes.Count > 0 ? $" [{string.Join(", ", attributes)}]" : "";
+            lines.Add($"{indent}\"{MapId(src)}\" -> \"{MapId(target)}\"{attrString};");
        }
    }

@@ -133,12 +153,7 @@ public static class WorkflowVisualizer

    private static void EmitWorkflowMermaid(Workflow workflow, List<string> lines, string indent, string? ns = null)
    {
-        string sanitize(string input)
-        {
-            return input;
-        }
-
-        string MapId(string id) => ns != null ? $"{sanitize(ns)}/{sanitize(id)}" : id;
+        string MapId(string id) => ns != null ? $"{ns}/{id}" : id;

        // Add start node
        var startExecutorId = workflow.StartExecutorId;
@@ -175,14 +190,23 @@ public static class WorkflowVisualizer
        }

        // Emit normal edges
-        foreach (var (src, target, isConditional) in ComputeNormalEdges(workflow))
+        foreach (var (src, target, isConditional, label) in ComputeNormalEdges(workflow))
        {
            if (isConditional)
            {
-                lines.Add($"{indent}{MapId(src)} -. conditional .--> {MapId(target)};");
+                string effectiveLabel = label != null ? EscapeMermaidLabel(label) : "conditional";
+
+                // Conditional edge, with user label or default
+                lines.Add($"{indent}{MapId(src)} -. {effectiveLabel} .--> {MapId(target)};");
+            }
+            else if (label != null)
+            {
+                // Regular edge with label
+                lines.Add($"{indent}{MapId(src)} -->|{EscapeMermaidLabel(label)}| {MapId(target)};");
            }
            else
            {
+                // Regular edge without label
                lines.Add($"{indent}{MapId(src)} --> {MapId(target)};");
            }
        }
@@ -214,9 +238,9 @@ public static class WorkflowVisualizer
        return result;
    }

-    private static List<(string Source, string Target, bool IsConditional)> ComputeNormalEdges(Workflow workflow)
+    private static List<(string Source, string Target, bool IsConditional, string? Label)> ComputeNormalEdges(Workflow workflow)
    {
-        var edges = new List<(string, string, bool)>();
+        var edges = new List<(string, string, bool, string?)>();
        foreach (var edgeGroup in workflow.Edges.Values.SelectMany(x => x))
        {
            if (edgeGroup.Kind == EdgeKind.FanIn)
@@ -229,14 +253,15 @@ public static class WorkflowVisualizer
                case EdgeKind.Direct when edgeGroup.DirectEdgeData != null:
                    var directData = edgeGroup.DirectEdgeData;
                    var isConditional = directData.Condition != null;
-                    edges.Add((directData.SourceId, directData.SinkId, isConditional));
+                    var label = directData.Label;
+                    edges.Add((directData.SourceId, directData.SinkId, isConditional, label));
                    break;

                case EdgeKind.FanOut when edgeGroup.FanOutEdgeData != null:
                    var fanOutData = edgeGroup.FanOutEdgeData;
                    foreach (var sinkId in fanOutData.SinkIds)
                    {
-                        edges.Add((fanOutData.SourceId, sinkId, false));
+                        edges.Add((fanOutData.SourceId, sinkId, false, fanOutData.Label));
                    }
                    break;
            }
@@ -276,5 +301,24 @@ public static class WorkflowVisualizer
        return false;
    }

+    // Helper method to escape special characters in DOT labels
+    private static string EscapeDotLabel(string label)
+    {
+        return label.Replace("\"", "\\\"").Replace("\n", "\\n");
+    }
+
+    // Helper method to escape special characters in Mermaid labels
+    private static string EscapeMermaidLabel(string label)
+    {
+        return label
+            .Replace("&", "&amp;")      // Must be first to avoid double-escaping
+            .Replace("|", "&#124;")     // Pipe breaks Mermaid delimiter syntax
+            .Replace("\"", "&quot;")    // Quote character
+            .Replace("<", "&lt;")       // Less than
+            .Replace(">", "&gt;")       // Greater than
+            .Replace("\n", "<br/>")     // Newline to HTML break
+            .Replace("\r", "");         // Remove carriage return
+    }
+
    #endregion
 }
@@ -168,6 +168,18 @@ public class WorkflowBuilder
        return edges;
    }

+    /// <summary>
+    /// Adds a directed edge from the specified source executor to the target executor, optionally guarded by a
+    /// condition.
+    /// </summary>
+    /// <param name="source">The executor that acts as the source node of the edge. Cannot be null.</param>
+    /// <param name="target">The executor that acts as the target node of the edge. Cannot be null.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    /// <exception cref="InvalidOperationException">Thrown if an unconditional edge between the specified source and target
+    /// executors already exists.</exception>
+    public WorkflowBuilder AddEdge(ExecutorBinding source, ExecutorBinding target)
+        => this.AddEdge<object>(source, target, null, false);
+
    /// <summary>
    /// Adds a directed edge from the specified source executor to the target executor, optionally guarded by a
    /// condition.
@@ -182,6 +194,20 @@ public class WorkflowBuilder
    public WorkflowBuilder AddEdge(ExecutorBinding source, ExecutorBinding target, bool idempotent = false)
        => this.AddEdge<object>(source, target, null, idempotent);

+    /// <summary>
+    /// Adds a directed edge from the specified source executor to the target executor.
+    /// </summary>
+    /// <param name="source">The executor that acts as the source node of the edge. Cannot be null.</param>
+    /// <param name="target">The executor that acts as the target node of the edge. Cannot be null.</param>
+    /// <param name="label">An optional label for the edge. Will be used in visualizations.</param>
+    /// <param name="idempotent">If set to <see langword="true"/>, adding the same edge multiple times will be a NoOp,
+    /// rather than an error.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    /// <exception cref="InvalidOperationException">Thrown if an unconditional edge between the specified source and target
+    /// executors already exists.</exception>
+    public WorkflowBuilder AddEdge(ExecutorBinding source, ExecutorBinding target, string? label = null, bool idempotent = false)
+        => this.AddEdge<object>(source, target, null, label, idempotent);
+
    internal static Func<object?, bool>? CreateConditionFunc<T>(Func<T?, bool>? condition)
    {
        if (condition is null)
@@ -222,6 +248,20 @@ public class WorkflowBuilder

    private EdgeId TakeEdgeId() => new(Interlocked.Increment(ref this._edgeCount));

+    /// <summary>
+    /// Adds a directed edge from the specified source executor to the target executor, optionally guarded by a
+    /// condition.
+    /// </summary>
+    /// <param name="source">The executor that acts as the source node of the edge. Cannot be null.</param>
+    /// <param name="target">The executor that acts as the target node of the edge. Cannot be null.</param>
+    /// <param name="condition">An optional predicate that determines whether the edge should be followed based on the input.
+    /// If null, the edge is always activated when the source sends a message.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    /// <exception cref="InvalidOperationException">Thrown if an unconditional edge between the specified source and target
+    /// executors already exists.</exception>
+    public WorkflowBuilder AddEdge<T>(ExecutorBinding source, ExecutorBinding target, Func<T?, bool>? condition = null)
+        => this.AddEdge(source, target, condition, label: null, false);
+
    /// <summary>
    /// Adds a directed edge from the specified source executor to the target executor, optionally guarded by a
    /// condition.
@@ -236,6 +276,23 @@ public class WorkflowBuilder
    /// <exception cref="InvalidOperationException">Thrown if an unconditional edge between the specified source and target
    /// executors already exists.</exception>
    public WorkflowBuilder AddEdge<T>(ExecutorBinding source, ExecutorBinding target, Func<T?, bool>? condition = null, bool idempotent = false)
+        => this.AddEdge(source, target, condition, label: null, idempotent);
+
+    /// <summary>
+    /// Adds a directed edge from the specified source executor to the target executor, optionally guarded by a
+    /// condition.
+    /// </summary>
+    /// <param name="source">The executor that acts as the source node of the edge. Cannot be null.</param>
+    /// <param name="target">The executor that acts as the target node of the edge. Cannot be null.</param>
+    /// <param name="condition">An optional predicate that determines whether the edge should be followed based on the input.
+    /// <param name="label">An optional label for the edge. Will be used in visualizations.</param>
+    /// <param name="idempotent">If set to <see langword="true"/>, adding the same edge multiple times will be a NoOp,
+    /// rather than an error.</param>
+    /// If null, the edge is always activated when the source sends a message.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    /// <exception cref="InvalidOperationException">Thrown if an unconditional edge between the specified source and target
+    /// executors already exists.</exception>
+    public WorkflowBuilder AddEdge<T>(ExecutorBinding source, ExecutorBinding target, Func<T?, bool>? condition = null, string? label = null, bool idempotent = false)
    {
        // Add an edge from source to target with an optional condition.
        // This is a low-level builder method that does not enforce any specific executor type.
@@ -256,7 +313,7 @@ public class WorkflowBuilder
                "You cannot add another edge without a condition for the same source and target.");
        }

-        DirectEdgeData directEdge = new(this.Track(source).Id, this.Track(target).Id, this.TakeEdgeId(), CreateConditionFunc(condition));
+        DirectEdgeData directEdge = new(this.Track(source).Id, this.Track(target).Id, this.TakeEdgeId(), CreateConditionFunc(condition), label);

        this.EnsureEdgesFor(source.Id).Add(new(directEdge));

@@ -275,6 +332,19 @@ public class WorkflowBuilder
    public WorkflowBuilder AddFanOutEdge(ExecutorBinding source, IEnumerable<ExecutorBinding> targets)
        => this.AddFanOutEdge<object>(source, targets, null);

+    /// <summary>
+    /// Adds a fan-out edge from the specified source executor to one or more target executors, optionally using a
+    /// custom partitioning function.
+    /// </summary>
+    /// <remarks>If a partitioner function is provided, it will be used to distribute input across the target
+    /// executors. The order of targets determines their mapping in the partitioning process.</remarks>
+    /// <param name="source">The source executor from which the fan-out edge originates. Cannot be null.</param>
+    /// <param name="targets">One or more target executors that will receive the fan-out edge. Cannot be null or empty.</param>
+    /// <param name="label">A label for the edge. Will be used in visualization.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    public WorkflowBuilder AddFanOutEdge(ExecutorBinding source, IEnumerable<ExecutorBinding> targets, string label)
+        => this.AddFanOutEdge<object>(source, targets, null, label);
+
    internal static Func<object?, int, IEnumerable<int>>? CreateTargetAssignerFunc<T>(Func<T?, int, IEnumerable<int>>? targetAssigner)
    {
        if (targetAssigner is null)
@@ -305,6 +375,21 @@ public class WorkflowBuilder
    /// <param name="targetSelector">An optional function that determines how input is assigned among the target executors.
    /// If null, messages will route to all targets.</param>
    public WorkflowBuilder AddFanOutEdge<T>(ExecutorBinding source, IEnumerable<ExecutorBinding> targets, Func<T?, int, IEnumerable<int>>? targetSelector = null)
+        => this.AddFanOutEdge(source, targets, targetSelector, label: null);
+
+    /// <summary>
+    /// Adds a fan-out edge from the specified source executor to one or more target executors, optionally using a
+    /// custom partitioning function.
+    /// </summary>
+    /// <remarks>If a partitioner function is provided, it will be used to distribute input across the target
+    /// executors. The order of targets determines their mapping in the partitioning process.</remarks>
+    /// <param name="source">The source executor from which the fan-out edge originates. Cannot be null.</param>
+    /// <param name="targets">One or more target executors that will receive the fan-out edge. Cannot be null or empty.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    /// <param name="targetSelector">An optional function that determines how input is assigned among the target executors.
+    /// If null, messages will route to all targets.</param>
+    /// <param name="label">An optional label for the edge. Will be used in visualizations.</param>
+    public WorkflowBuilder AddFanOutEdge<T>(ExecutorBinding source, IEnumerable<ExecutorBinding> targets, Func<T?, int, IEnumerable<int>>? targetSelector = null, string? label = null)
    {
        Throw.IfNull(source);
        Throw.IfNull(targets);
@@ -321,7 +406,8 @@ public class WorkflowBuilder
            this.Track(source).Id,
            sinkIds,
            this.TakeEdgeId(),
-            CreateTargetAssignerFunc(targetSelector));
+            CreateTargetAssignerFunc(targetSelector),
+            label);

        this.EnsureEdgesFor(source.Id).Add(new(fanOutEdge));

@@ -339,6 +425,20 @@ public class WorkflowBuilder
    /// <param name="target">The target executor that receives input from the specified source executors. Cannot be null.</param>
    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
    public WorkflowBuilder AddFanInEdge(IEnumerable<ExecutorBinding> sources, ExecutorBinding target)
+        => this.AddFanInEdge(sources, target, label: null);
+
+    /// <summary>
+    /// Adds a fan-in edge to the workflow, connecting multiple source executors to a single target executor with an
+    /// optional trigger condition.
+    /// </summary>
+    /// <remarks>This method establishes a fan-in relationship, allowing the target executor to be activated
+    /// based on the completion or state of multiple sources. The trigger parameter can be used to customize activation
+    /// behavior.</remarks>
+    /// <param name="sources">One or more source executors that provide input to the target. Cannot be null or empty.</param>
+    /// <param name="target">The target executor that receives input from the specified source executors. Cannot be null.</param>
+    /// <param name="label">An optional label for the edge. Will be used in visualizations.</param>
+    /// <returns>The current instance of <see cref="WorkflowBuilder"/>.</returns>
+    public WorkflowBuilder AddFanInEdge(IEnumerable<ExecutorBinding> sources, ExecutorBinding target, string? label = null)
    {
        Throw.IfNull(target);
        Throw.IfNull(sources);
@@ -354,7 +454,8 @@ public class WorkflowBuilder
        FanInEdgeData edgeData = new(
            sourceIds,
            this.Track(target).Id,
-            this.TakeEdgeId());
+            this.TakeEdgeId(),
+            label);

        foreach (string sourceId in edgeData.SourceIds)
        {
@@ -114,7 +114,9 @@ public sealed class OpenTelemetryAgent : DelegatingAIAgent, IDisposable

        // Override information set by OpenTelemetryChatClient to make it specific to invoke_agent.

-        activity.DisplayName = $"{OpenTelemetryConsts.GenAI.InvokeAgent} {this.DisplayName}";
+        activity.DisplayName = string.IsNullOrWhiteSpace(this.Name)
+            ? $"{OpenTelemetryConsts.GenAI.InvokeAgent} {this.Id}"
+            : $"{OpenTelemetryConsts.GenAI.InvokeAgent} {this.Name}({this.Id})";
        activity.SetTag(OpenTelemetryConsts.GenAI.Operation.Name, OpenTelemetryConsts.GenAI.InvokeAgent);

        if (!string.IsNullOrWhiteSpace(this._providerName))
@@ -89,7 +89,7 @@ public class AIProjectClientFixture : IChatClientAgentFixture
        List<ChatMessage> messages = [];
        await foreach (AgentResponseItem item in this._client.GetProjectOpenAIClient().GetProjectConversationsClient().GetProjectConversationItemsAsync(conversationId, order: "asc"))
        {
-            var openAIItem = item.AsOpenAIResponseItem();
+            var openAIItem = item.AsResponseResultItem();
            if (openAIItem is MessageResponseItem messageItem)
            {
                messages.Add(new ChatMessage
@@ -42,16 +42,14 @@ public sealed class A2AAgentTests : IDisposable
        const string TestId = "test-id";
        const string TestName = "test-name";
        const string TestDescription = "test-description";
-        const string TestDisplayName = "test-display-name";

        // Act
-        var agent = new A2AAgent(this._a2aClient, TestId, TestName, TestDescription, TestDisplayName);
+        var agent = new A2AAgent(this._a2aClient, TestId, TestName, TestDescription);

        // Assert
        Assert.Equal(TestId, agent.Id);
        Assert.Equal(TestName, agent.Name);
        Assert.Equal(TestDescription, agent.Description);
-        Assert.Equal(TestDisplayName, agent.DisplayName);
    }

    [Fact]
@@ -70,7 +68,6 @@ public sealed class A2AAgentTests : IDisposable
        Assert.NotEmpty(agent.Id);
        Assert.Null(agent.Name);
        Assert.Null(agent.Description);
-        Assert.Equal(agent.Id, agent.DisplayName);
    }

    [Fact]
@@ -19,10 +19,9 @@ public sealed class A2AClientExtensionsTests
        const string TestId = "test-agent-id";
        const string TestName = "Test Agent";
        const string TestDescription = "This is a test agent description";
-        const string TestDisplayName = "Test Display Name";

        // Act
-        var agent = a2aClient.GetAIAgent(TestId, TestName, TestDescription, TestDisplayName);
+        var agent = a2aClient.GetAIAgent(TestId, TestName, TestDescription);

        // Assert
        Assert.NotNull(agent);
@@ -30,6 +29,5 @@ public sealed class A2AClientExtensionsTests
        Assert.Equal(TestId, agent.Id);
        Assert.Equal(TestName, agent.Name);
        Assert.Equal(TestDescription, agent.Description);
-        Assert.Equal(TestDisplayName, agent.DisplayName);
    }
 }
@@ -10,7 +10,6 @@ using Azure.Core;
 using Azure.Identity;
 using Microsoft.Azure.Cosmos;
 using Microsoft.Extensions.AI;
-using Xunit;

 namespace Microsoft.Agents.AI.CosmosNoSql.UnitTests;

@@ -59,6 +58,9 @@ public sealed class CosmosChatMessageStoreTests : IAsyncLifetime, IDisposable

    public async Task InitializeAsync()
    {
+        // Fail fast if emulator is not available
+        this.SkipIfEmulatorNotAvailable();
+
        // Check environment variable to determine if we should preserve containers
        // Set COSMOS_PRESERVE_CONTAINERS=true to keep containers and data for inspection
        this._preserveContainer = string.Equals(Environment.GetEnvironmentVariable("COSMOS_PRESERVE_CONTAINERS"), "true", StringComparison.OrdinalIgnoreCase);
@@ -7,7 +7,6 @@ using System.Threading.Tasks;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Agents.AI.Workflows.Checkpointing;
 using Microsoft.Azure.Cosmos;
-using Xunit;

 namespace Microsoft.Agents.AI.CosmosNoSql.UnitTests;

@@ -58,6 +57,9 @@ public class CosmosCheckpointStoreTests : IAsyncLifetime, IDisposable

    public async Task InitializeAsync()
    {
+        // Fail fast if emulator is not available
+        this.SkipIfEmulatorNotAvailable();
+
        // Check environment variable to determine if we should preserve containers
        // Set COSMOS_PRESERVE_CONTAINERS=true to keep containers and data for inspection
        this._preserveContainer = string.Equals(Environment.GetEnvironmentVariable("COSMOS_PRESERVE_CONTAINERS"), "true", StringComparison.OrdinalIgnoreCase);
@@ -81,6 +81,64 @@ public sealed class AgentEntityTests(ITestOutputHelper outputHelper) : IDisposab
        Assert.Null(request.OrchestrationId);
    }

+    [Theory]
+    [InlineData("run")]
+    [InlineData("Run")]
+    [InlineData("RunAgentAsync")]
+    public async Task RunAgentMethodNamesAllWorkAsync(string runAgentMethodName)
+    {
+        // Setup
+        AIAgent simpleAgent = TestHelper.GetAzureOpenAIChatClient(s_configuration).CreateAIAgent(
+            name: "TestAgent",
+            instructions: "You are a helpful assistant that always responds with a friendly greeting."
+        );
+
+        using TestHelper testHelper = TestHelper.Start([simpleAgent], this._outputHelper);
+
+        // A proxy agent is needed to call the hosted test agent
+        AIAgent simpleAgentProxy = simpleAgent.AsDurableAgentProxy(testHelper.Services);
+
+        AgentThread thread = simpleAgentProxy.GetNewThread();
+
+        DurableTaskClient client = testHelper.GetClient();
+
+        AgentSessionId sessionId = thread.GetService<AgentSessionId>();
+        EntityInstanceId expectedEntityId = new($"dafx-{simpleAgent.Name}", sessionId.Key);
+
+        EntityMetadata? entity = await client.Entities.GetEntityAsync(expectedEntityId, false, this.TestTimeoutToken);
+
+        Assert.Null(entity);
+
+        // Act: send a prompt to the agent
+        await client.Entities.SignalEntityAsync(
+            expectedEntityId,
+            runAgentMethodName,
+            new RunRequest("Hello!"),
+            cancellation: this.TestTimeoutToken);
+
+        while (!this.TestTimeoutToken.IsCancellationRequested)
+        {
+            await Task.Delay(500, this.TestTimeoutToken);
+
+            // Assert: verify the agent state was stored with the correct entity name prefix
+            entity = await client.Entities.GetEntityAsync(expectedEntityId, true, this.TestTimeoutToken);
+
+            if (entity is not null)
+            {
+                break;
+            }
+        }
+
+        Assert.NotNull(entity);
+        Assert.True(entity.IncludesState);
+
+        DurableAgentState state = entity.State.ReadAs<DurableAgentState>();
+
+        DurableAgentStateRequest request = Assert.Single(state.Data.ConversationHistory.OfType<DurableAgentStateRequest>());
+
+        Assert.Null(request.OrchestrationId);
+    }
+
    [Fact]
    public async Task OrchestrationIdSetDuringOrchestrationAsync()
    {
@@ -0,0 +1,197 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Reflection;
+using Microsoft.Agents.AI.DurableTask.State;
+using Microsoft.DurableTask.Client;
+using Microsoft.DurableTask.Client.Entities;
+using Microsoft.Extensions.Configuration;
+using OpenAI.Chat;
+using Xunit.Abstractions;
+
+namespace Microsoft.Agents.AI.DurableTask.IntegrationTests;
+
+/// <summary>
+/// Tests for Time-To-Live (TTL) functionality of durable agent entities.
+/// </summary>
+[Collection("Sequential")]
+[Trait("Category", "Integration")]
+public sealed class TimeToLiveTests(ITestOutputHelper outputHelper) : IDisposable
+{
+    private static readonly TimeSpan s_defaultTimeout = Debugger.IsAttached
+        ? TimeSpan.FromMinutes(5)
+        : TimeSpan.FromSeconds(30);
+
+    private static readonly IConfiguration s_configuration =
+        new ConfigurationBuilder()
+            .AddUserSecrets(Assembly.GetExecutingAssembly())
+            .AddEnvironmentVariables()
+            .Build();
+
+    private readonly ITestOutputHelper _outputHelper = outputHelper;
+    private readonly CancellationTokenSource _cts = new(delay: s_defaultTimeout);
+
+    private CancellationToken TestTimeoutToken => this._cts.Token;
+
+    public void Dispose() => this._cts.Dispose();
+
+    [Fact]
+    public async Task EntityExpiresAfterTTLAsync()
+    {
+        // Arrange: Create agent with short TTL (10 seconds)
+        TimeSpan ttl = TimeSpan.FromSeconds(10);
+        AIAgent simpleAgent = TestHelper.GetAzureOpenAIChatClient(s_configuration).CreateAIAgent(
+            name: "TTLTestAgent",
+            instructions: "You are a helpful assistant."
+        );
+
+        using TestHelper testHelper = TestHelper.Start(
+            this._outputHelper,
+            options =>
+            {
+                options.DefaultTimeToLive = ttl;
+                options.MinimumTimeToLiveSignalDelay = TimeSpan.FromSeconds(1);
+                options.AddAIAgent(simpleAgent);
+            });
+
+        AIAgent agentProxy = simpleAgent.AsDurableAgentProxy(testHelper.Services);
+        AgentThread thread = agentProxy.GetNewThread();
+        DurableTaskClient client = testHelper.GetClient();
+        AgentSessionId sessionId = thread.GetService<AgentSessionId>();
+
+        // Act: Send a message to the agent
+        await agentProxy.RunAsync(
+            message: "Hello!",
+            thread,
+            cancellationToken: this.TestTimeoutToken);
+
+        // Verify entity exists and get expiration time
+        EntityMetadata? entity = await client.Entities.GetEntityAsync(sessionId, true, this.TestTimeoutToken);
+        Assert.NotNull(entity);
+        Assert.True(entity.IncludesState);
+
+        DurableAgentState state = entity.State.ReadAs<DurableAgentState>();
+        Assert.NotNull(state.Data.ExpirationTimeUtc);
+        DateTime expirationTime = state.Data.ExpirationTimeUtc.Value;
+        Assert.True(expirationTime > DateTime.UtcNow);
+
+        // Calculate how long to wait: expiration time + buffer for signal processing
+        TimeSpan waitTime = expirationTime - DateTime.UtcNow + TimeSpan.FromSeconds(1);
+        if (waitTime > TimeSpan.Zero)
+        {
+            await Task.Delay(waitTime, this.TestTimeoutToken);
+        }
+
+        // Poll the entity state until it's deleted (with timeout)
+        DateTime pollTimeout = DateTime.UtcNow.AddSeconds(10);
+        bool entityDeleted = false;
+        while (DateTime.UtcNow < pollTimeout && !entityDeleted)
+        {
+            entity = await client.Entities.GetEntityAsync(sessionId, true, this.TestTimeoutToken);
+            entityDeleted = entity is null;
+
+            if (!entityDeleted)
+            {
+                await Task.Delay(TimeSpan.FromSeconds(1), this.TestTimeoutToken);
+            }
+        }
+
+        // Assert: Verify entity state is deleted
+        Assert.True(entityDeleted, "Entity should have been deleted after TTL expiration");
+    }
+
+    [Fact]
+    public async Task EntityTTLResetsOnInteractionAsync()
+    {
+        // Arrange: Create agent with short TTL
+        TimeSpan ttl = TimeSpan.FromSeconds(6);
+        AIAgent simpleAgent = TestHelper.GetAzureOpenAIChatClient(s_configuration).CreateAIAgent(
+            name: "TTLResetTestAgent",
+            instructions: "You are a helpful assistant."
+        );
+
+        using TestHelper testHelper = TestHelper.Start(
+            this._outputHelper,
+            options =>
+            {
+                options.DefaultTimeToLive = ttl;
+                options.MinimumTimeToLiveSignalDelay = TimeSpan.FromSeconds(1);
+                options.AddAIAgent(simpleAgent);
+            });
+
+        AIAgent agentProxy = simpleAgent.AsDurableAgentProxy(testHelper.Services);
+        AgentThread thread = agentProxy.GetNewThread();
+        DurableTaskClient client = testHelper.GetClient();
+        AgentSessionId sessionId = thread.GetService<AgentSessionId>();
+
+        // Act: Send first message
+        await agentProxy.RunAsync(
+            message: "Hello!",
+            thread,
+            cancellationToken: this.TestTimeoutToken);
+
+        EntityMetadata? entity = await client.Entities.GetEntityAsync(sessionId, true, this.TestTimeoutToken);
+        Assert.NotNull(entity);
+        Assert.True(entity.IncludesState);
+
+        DurableAgentState state = entity.State.ReadAs<DurableAgentState>();
+        DateTime firstExpirationTime = state.Data.ExpirationTimeUtc!.Value;
+
+        // Wait partway through TTL
+        await Task.Delay(TimeSpan.FromSeconds(3), this.TestTimeoutToken);
+
+        // Send second message (should reset TTL)
+        await agentProxy.RunAsync(
+            message: "Hello again!",
+            thread,
+            cancellationToken: this.TestTimeoutToken);
+
+        // Verify expiration time was updated
+        entity = await client.Entities.GetEntityAsync(sessionId, true, this.TestTimeoutToken);
+        Assert.NotNull(entity);
+        Assert.True(entity.IncludesState);
+
+        state = entity.State.ReadAs<DurableAgentState>();
+        DateTime secondExpirationTime = state.Data.ExpirationTimeUtc!.Value;
+        Assert.True(secondExpirationTime > firstExpirationTime);
+
+        // Calculate when the original expiration time would have been
+        DateTime originalExpirationTime = firstExpirationTime;
+        TimeSpan waitUntilOriginalExpiration = originalExpirationTime - DateTime.UtcNow + TimeSpan.FromSeconds(2);
+
+        if (waitUntilOriginalExpiration > TimeSpan.Zero)
+        {
+            await Task.Delay(waitUntilOriginalExpiration, this.TestTimeoutToken);
+        }
+
+        // Assert: Entity should still exist because TTL was reset
+        // The new expiration time should be in the future
+        entity = await client.Entities.GetEntityAsync(sessionId, true, this.TestTimeoutToken);
+        Assert.NotNull(entity);
+        Assert.True(entity.IncludesState);
+
+        state = entity.State.ReadAs<DurableAgentState>();
+        Assert.NotNull(state);
+        Assert.NotNull(state.Data.ExpirationTimeUtc);
+        Assert.True(
+            state.Data.ExpirationTimeUtc > DateTime.UtcNow,
+            "Entity should still be valid because TTL was reset");
+
+        // Wait for the entity to be deleted
+        DateTime pollTimeout = DateTime.UtcNow.AddSeconds(10);
+        bool entityDeleted = false;
+        while (DateTime.UtcNow < pollTimeout && !entityDeleted)
+        {
+            entity = await client.Entities.GetEntityAsync(sessionId, true, this.TestTimeoutToken);
+            entityDeleted = entity is null;
+
+            if (!entityDeleted)
+            {
+                await Task.Delay(TimeSpan.FromSeconds(1), this.TestTimeoutToken);
+            }
+        }
+
+        // Assert: Entity should have been deleted
+        Assert.True(entityDeleted, "Entity should have been deleted after TTL expiration");
+    }
+}
@@ -49,7 +49,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "One Two Three";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Count to 3");
@@ -90,10 +90,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Hello! How can I help you today?";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Hello");
+        ResponseResult response = await responseClient.CreateResponseAsync("Hello");

        // Assert
        Assert.NotNull(response);
@@ -117,7 +117,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "This is a test response with multiple words";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -162,12 +162,12 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            (Agent1Name, Agent1Instructions, Agent1Response),
            (Agent2Name, Agent2Instructions, Agent2Response));

-        OpenAIResponseClient responseClient1 = this.CreateResponseClient(Agent1Name);
-        OpenAIResponseClient responseClient2 = this.CreateResponseClient(Agent2Name);
+        ResponsesClient responseClient1 = this.CreateResponseClient(Agent1Name);
+        ResponsesClient responseClient2 = this.CreateResponseClient(Agent2Name);

        // Act
-        OpenAIResponse response1 = await responseClient1.CreateResponseAsync("Hello");
-        OpenAIResponse response2 = await responseClient2.CreateResponseAsync("Hello");
+        ResponseResult response1 = await responseClient1.CreateResponseAsync("Hello");
+        ResponseResult response2 = await responseClient2.CreateResponseAsync("Hello");

        // Assert
        string content1 = response1.GetOutputText();
@@ -190,10 +190,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "This is the response";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act - Non-streaming
-        OpenAIResponse nonStreamingResponse = await responseClient.CreateResponseAsync("Test");
+        ResponseResult nonStreamingResponse = await responseClient.CreateResponseAsync("Test");

        // Act - Streaming
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -224,10 +224,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Complete";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Test");
+        ResponseResult response = await responseClient.CreateResponseAsync("Test");

        // Assert
        Assert.Equal(ResponseStatus.Completed, response.Status);
@@ -247,7 +247,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Test response with multiple words";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -286,7 +286,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -316,10 +316,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Response with metadata";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Test");
+        ResponseResult response = await responseClient.CreateResponseAsync("Test");

        // Assert
        Assert.NotNull(response.Id);
@@ -340,7 +340,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        string expectedResponse = string.Join(" ", Enumerable.Range(1, 100).Select(i => $"Word{i}"));

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, expectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Generate long text");
@@ -371,7 +371,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Test output index";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -407,7 +407,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Hello";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -437,7 +437,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Hello! How are you? I'm fine. 100% great!";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -467,10 +467,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Symbols: @#$%^&*() Quotes: \"Hello\" 'World' Unicode: 你好 🌍";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Test");
+        ResponseResult response = await responseClient.CreateResponseAsync("Test");

        // Assert
        string content = response.GetOutputText();
@@ -489,7 +489,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Testing item IDs";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -525,12 +525,12 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Response";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act & Assert - Make 5 sequential requests
        for (int i = 0; i < 5; i++)
        {
-            OpenAIResponse response = await responseClient.CreateResponseAsync($"Request {i}");
+            ResponseResult response = await responseClient.CreateResponseAsync($"Request {i}");
            Assert.NotNull(response);
            Assert.Equal(ResponseStatus.Completed, response.Status);
            Assert.Equal(ExpectedResponse, response.GetOutputText());
@@ -549,7 +549,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Streaming response";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act & Assert - Make 3 sequential streaming requests
        for (int i = 0; i < 3; i++)
@@ -581,13 +581,13 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Response";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        List<string> responseIds = [];
        for (int i = 0; i < 10; i++)
        {
-            OpenAIResponse response = await responseClient.CreateResponseAsync($"Request {i}");
+            ResponseResult response = await responseClient.CreateResponseAsync($"Request {i}");
            responseIds.Add(response.Id);
        }

@@ -608,7 +608,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Test sequence numbers with multiple words";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -641,10 +641,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Test model info";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Test");
+        ResponseResult response = await responseClient.CreateResponseAsync("Test");

        // Assert
        Assert.NotNull(response.Model);
@@ -663,7 +663,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Hello, world! How are you today? I'm doing well.";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -693,10 +693,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "OK";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Hi");
+        ResponseResult response = await responseClient.CreateResponseAsync("Hi");

        // Assert
        Assert.NotNull(response);
@@ -716,7 +716,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Test content indices";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -748,10 +748,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Line 1\nLine 2\nLine 3";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Test");
+        ResponseResult response = await responseClient.CreateResponseAsync("Test");

        // Assert
        string content = response.GetOutputText();
@@ -771,7 +771,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "First line\nSecond line\nThird line";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -807,10 +807,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.ImageContentMockChatClient(ImageUrl));

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Show me an image");
+        ResponseResult response = await responseClient.CreateResponseAsync("Show me an image");

        // Assert
        Assert.NotNull(response);
@@ -834,7 +834,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.ImageContentMockChatClient(ImageUrl));

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Show me an image");
@@ -868,10 +868,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.AudioContentMockChatClient(AudioData, Transcript));

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Generate audio");
+        ResponseResult response = await responseClient.CreateResponseAsync("Generate audio");

        // Assert
        Assert.NotNull(response);
@@ -896,7 +896,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.AudioContentMockChatClient(AudioData, Transcript));

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Generate audio");
@@ -930,10 +930,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.FunctionCallMockChatClient(FunctionName, Arguments));

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("What's the weather?");
+        ResponseResult response = await responseClient.CreateResponseAsync("What's the weather?");

        // Assert
        Assert.NotNull(response);
@@ -957,7 +957,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.FunctionCallMockChatClient(FunctionName, Arguments));

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Calculate 2+2");
@@ -988,10 +988,10 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.MixedContentMockChatClient());

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
-        OpenAIResponse response = await responseClient.CreateResponseAsync("Show me various content");
+        ResponseResult response = await responseClient.CreateResponseAsync("Show me various content");

        // Assert
        Assert.NotNull(response);
@@ -1014,7 +1014,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
            instructions: Instructions,
            chatClient: new TestHelpers.MixedContentMockChatClient());

-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Show me various content");
@@ -1047,7 +1047,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Complete text response";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -1075,7 +1075,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        const string ExpectedResponse = "Response with content parts";

        this._httpClient = await this.CreateTestServerAsync(AgentName, Instructions, ExpectedResponse);
-        OpenAIResponseClient responseClient = this.CreateResponseClient(AgentName);
+        ResponsesClient responseClient = this.CreateResponseClient(AgentName);

        // Act
        AsyncCollectionResult<StreamingResponseUpdate> streamingResult = responseClient.CreateResponseStreamingAsync("Test");
@@ -1122,7 +1122,7 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        string conversationId = convDoc.RootElement.GetProperty("id").GetString()!;

        // Act - Send request with conversation ID using raw HTTP
-        // (OpenAI SDK doesn't expose ConversationId directly on ResponseCreationOptions)
+        // (OpenAI SDK doesn't expose ConversationId directly on CreateResponseOptions)
        var requestBody = new
        {
            input = "Test",
@@ -1201,9 +1201,9 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
        Assert.Null(mockChatClient.LastChatOptions.ConversationId);
    }

-    private OpenAIResponseClient CreateResponseClient(string agentName)
+    private ResponsesClient CreateResponseClient(string agentName)
    {
-        return new OpenAIResponseClient(
+        return new ResponsesClient(
            model: "test-model",
            credential: new ApiKeyCredential("test-api-key"),
            options: new OpenAIClientOptions
@@ -55,9 +55,9 @@ public sealed class OpenAIResponseClientExtensionsTests
    }

    /// <summary>
-    /// Creates a test OpenAIResponseClient implementation for testing.
+    /// Creates a test ResponsesClient implementation for testing.
    /// </summary>
-    private sealed class TestOpenAIResponseClient : OpenAIResponseClient
+    private sealed class TestOpenAIResponseClient : ResponsesClient
    {
        public TestOpenAIResponseClient()
        {
@@ -147,7 +147,7 @@ public sealed class OpenAIResponseClientExtensionsTests
    {
        // Act & Assert
        var exception = Assert.Throws<ArgumentNullException>(() =>
-            ((OpenAIResponseClient)null!).CreateAIAgent());
+            ((ResponsesClient)null!).CreateAIAgent());

        Assert.Equal("client", exception.ParamName);
    }
@@ -42,7 +42,6 @@ public class LoggingAgentTests
        Assert.Equal("TestAgent", agent.Name);
        Assert.Equal("This is a test agent.", agent.Description);
        Assert.Equal(innerAgent.Id, agent.Id);
-        Assert.Equal(innerAgent.DisplayName, agent.DisplayName);
    }

    [Fact]
@@ -45,7 +45,6 @@ public class OpenTelemetryAgentTests
        Assert.Equal("TestAgent", agent.Name);
        Assert.Equal("This is a test agent.", agent.Description);
        Assert.Equal(innerAgent.Id, agent.Id);
-        Assert.Equal(innerAgent.DisplayName, agent.DisplayName);
    }

    [Fact]
@@ -170,7 +169,7 @@ public class OpenTelemetryAgentTests
        Assert.Equal("localhost", activity.GetTagItem("server.address"));
        Assert.Equal(12345, (int)activity.GetTagItem("server.port")!);

-        Assert.Equal("invoke_agent TestAgent", activity.DisplayName);
+        Assert.Equal($"invoke_agent {agent.Name}({agent.Id})", activity.DisplayName);
        Assert.Equal("invoke_agent", activity.GetTagItem("gen_ai.operation.name"));
        Assert.Equal("TestAgentProviderFromAIAgentMetadata", activity.GetTagItem("gen_ai.provider.name"));
        Assert.Equal(innerAgent.Name, activity.GetTagItem("gen_ai.agent.name"));
@@ -431,7 +430,15 @@ public class OpenTelemetryAgentTests
        Assert.Equal("localhost", activity.GetTagItem("server.address"));
        Assert.Equal(12345, (int)activity.GetTagItem("server.port")!);

-        Assert.Equal($"invoke_agent {innerAgent.DisplayName}", activity.DisplayName);
+        if (string.IsNullOrWhiteSpace(innerAgent.Name))
+        {
+            Assert.Equal($"invoke_agent {innerAgent.Id}", activity.DisplayName);
+        }
+        else
+        {
+            Assert.Equal($"invoke_agent {innerAgent.Name}({innerAgent.Id})", activity.DisplayName);
+        }
+
        Assert.Equal("invoke_agent", activity.GetTagItem("gen_ai.operation.name"));
        Assert.Equal("TestAgentProviderFromAIAgentMetadata", activity.GetTagItem("gen_ai.provider.name"));
        Assert.Equal(innerAgent.Name, activity.GetTagItem("gen_ai.agent.name"));
@@ -24,7 +24,7 @@ public sealed class MediaInputTest(ITestOutputHelper output) : IntegrationTest(o
    private const string ImageReference = "https://sample-files.com/downloads/images/jpg/web_optimized_1200x800_97kb.jpg";

    [Theory]
-    [InlineData(ImageReference, "image/jpeg")]
+    [InlineData(ImageReference, "image/jpeg", Skip = "Failing consistently in the agent service api")]
    [InlineData(PdfReference, "application/pdf", Skip = "Not currently supported by agent service api")]
    public async Task ValidateFileUrlAsync(string fileSource, string mediaType)
    {
@@ -21,7 +21,7 @@ public class EdgeMapSmokeTests

        Dictionary<string, HashSet<Edge>> workflowEdges = [];

-        FanInEdgeData edgeData = new(["executor1", "executor2"], "executor3", new EdgeId(0));
+        FanInEdgeData edgeData = new(["executor1", "executor2"], "executor3", new EdgeId(0), null);
        Edge fanInEdge = new(edgeData);

        workflowEdges["executor1"] = [fanInEdge];
@@ -155,7 +155,7 @@ public class EdgeRunnerTests
        runContext.Executors["executor2"] = new ForwardMessageExecutor<string>("executor2");
        runContext.Executors["executor3"] = new ForwardMessageExecutor<string>("executor3");

-        FanInEdgeData edgeData = new(["executor1", "executor2"], "executor3", new EdgeId(0));
+        FanInEdgeData edgeData = new(["executor1", "executor2"], "executor3", new EdgeId(0), null);
        FanInEdgeRunner runner = new(runContext, edgeData);

        // Step 1: Send message from executor1, should not forward yet.
@@ -118,7 +118,7 @@ public class JsonSerializationTests
        RunJsonRoundtrip(TestFanOutEdgeInfo_Assigner, predicate: TestFanOutEdgeInfo_Assigner.CreateValidator());
    }

-    private static FanInEdgeData TestFanInEdgeData => new(["SourceExecutor1", "SourceExecutor2"], "TargetExecutor", TakeEdgeId());
+    private static FanInEdgeData TestFanInEdgeData => new(["SourceExecutor1", "SourceExecutor2"], "TargetExecutor", TakeEdgeId(), null);
    private static FanInEdgeInfo TestFanInEdgeInfo => new(TestFanInEdgeData);

    [Fact]
@@ -137,17 +137,17 @@ public class RepresentationTests
        RunEdgeInfoMatchTest(fanOutEdgeWithAssigner);

        // FanIn Edges
-        Edge fanInEdge = new(new FanInEdgeData([Source(1), Source(2), Source(3)], Sink(1), TakeEdgeId()));
+        Edge fanInEdge = new(new FanInEdgeData([Source(1), Source(2), Source(3)], Sink(1), TakeEdgeId(), null));
        RunEdgeInfoMatchTest(fanInEdge);

-        Edge fanInEdge2 = new(new FanInEdgeData([Source(1), Source(2), Source(3)], Sink(1), TakeEdgeId()));
+        Edge fanInEdge2 = new(new FanInEdgeData([Source(1), Source(2), Source(3)], Sink(1), TakeEdgeId(), null));
        RunEdgeInfoMatchTest(fanInEdge, fanInEdge2);

-        Edge fanInEdge3 = new(new FanInEdgeData([Source(2), Source(3), Source(1)], Sink(1), TakeEdgeId()));
+        Edge fanInEdge3 = new(new FanInEdgeData([Source(2), Source(3), Source(1)], Sink(1), TakeEdgeId(), null));
        RunEdgeInfoMatchTest(fanInEdge, fanInEdge3, expect: false); // Order matters (though for FanIn maybe it shouldn't?)

-        Edge fanInEdge4 = new(new FanInEdgeData([Source(1), Source(2), Source(4)], Sink(1), TakeEdgeId()));
-        Edge fanInEdge5 = new(new FanInEdgeData([Source(1), Source(2), Source(3)], Sink(2), TakeEdgeId()));
+        Edge fanInEdge4 = new(new FanInEdgeData([Source(1), Source(2), Source(4)], Sink(1), TakeEdgeId(), null));
+        Edge fanInEdge5 = new(new FanInEdgeData([Source(1), Source(2), Source(3)], Sink(2), TakeEdgeId(), null));
        RunEdgeInfoMatchTest(fanInEdge, fanInEdge4, expect: false); // Identity matters
        RunEdgeInfoMatchTest(fanInEdge, fanInEdge5, expect: false);

@@ -30,7 +30,7 @@ internal sealed class HandoffTestEchoAgent(string id, string name, string prefix
                {
                    return [new(ChatRole.Assistant, [new FunctionCallContent(Guid.NewGuid().ToString("N"), handoff.Name)])
                    {
-                        AuthorName = this.DisplayName,
+                        AuthorName = this.Name ?? this.Id,
                        MessageId = Guid.NewGuid().ToString("N"),
                        CreatedAt = DateTime.UtcNow
                    }];
@@ -47,7 +47,7 @@ internal class TestEchoAgent(string? id = null, string? name = null, string? pre
              select
                    UpdateThread(new ChatMessage(ChatRole.Assistant, $"{prefix}{message.Text}")
                    {
-                        AuthorName = this.DisplayName,
+                        AuthorName = this.Name ?? this.Id,
                        CreatedAt = DateTimeOffset.Now,
                        MessageId = Guid.NewGuid().ToString("N")
                    }, thread as InMemoryAgentThread);
@@ -394,4 +394,61 @@ public class WorkflowVisualizerTests
        // Check fan-in (should have intermediate node)
        mermaidContent.Should().Contain("((fan-in))");
    }
+
+    [Fact]
+    public void Test_WorkflowViz_Mermaid_Edge_Label_With_Pipe()
+    {
+        // Test that pipe characters in labels are properly escaped
+        var start = new MockExecutor("start");
+        var end = new MockExecutor("end");
+
+        var workflow = new WorkflowBuilder("start")
+            .AddEdge(start, end, label: "High | Low Priority")
+            .Build();
+
+        var mermaidContent = workflow.ToMermaidString();
+
+        // Should escape pipe character
+        mermaidContent.Should().Contain("start -->|High &#124; Low Priority| end");
+        // Should not contain unescaped pipe that would break syntax
+        mermaidContent.Should().NotContain("-->|High | Low");
+    }
+
+    [Fact]
+    public void Test_WorkflowViz_Mermaid_Edge_Label_With_Special_Chars()
+    {
+        // Test that special characters are properly escaped
+        var start = new MockExecutor("start");
+        var end = new MockExecutor("end");
+
+        var workflow = new WorkflowBuilder("start")
+            .AddEdge(start, end, label: "Score >= 90 & < 100")
+            .Build();
+
+        var mermaidContent = workflow.ToMermaidString();
+
+        // Should escape special characters
+        mermaidContent.Should().Contain("&amp;");
+        mermaidContent.Should().Contain("&gt;");
+        mermaidContent.Should().Contain("&lt;");
+    }
+
+    [Fact]
+    public void Test_WorkflowViz_Mermaid_Edge_Label_With_Newline()
+    {
+        // Test that newlines are converted to <br/>
+        var start = new MockExecutor("start");
+        var end = new MockExecutor("end");
+
+        var workflow = new WorkflowBuilder("start")
+            .AddEdge(start, end, label: "Line 1\nLine 2")
+            .Build();
+
+        var mermaidContent = workflow.ToMermaidString();
+
+        // Should convert newline to <br/>
+        mermaidContent.Should().Contain("Line 1<br/>Line 2");
+        // Should not contain literal newline in the label (but the overall output has newlines between statements)
+        mermaidContent.Should().NotContain("Line 1\nLine 2");
+    }
 }
@@ -3,11 +3,11 @@
 using System.Threading.Tasks;
 using AgentConformance.IntegrationTests;

-namespace OpenAIResponse.IntegrationTests;
+namespace ResponseResult.IntegrationTests;

 public class OpenAIResponseStoreTrueChatClientAgentRunStreamingTests() : ChatClientAgentRunStreamingTests<OpenAIResponseFixture>(() => new(store: true))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";

    [Fact(Skip = SkipReason)]
    public override Task RunWithInstructionsAndNoMessageReturnsExpectedResultAsync() =>
@@ -16,7 +16,7 @@ public class OpenAIResponseStoreTrueChatClientAgentRunStreamingTests() : ChatCli

 public class OpenAIResponseStoreFalseChatClientAgentRunStreamingTests() : ChatClientAgentRunStreamingTests<OpenAIResponseFixture>(() => new(store: false))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";

    [Fact(Skip = SkipReason)]
    public override Task RunWithInstructionsAndNoMessageReturnsExpectedResultAsync() =>
@@ -3,11 +3,11 @@
 using System.Threading.Tasks;
 using AgentConformance.IntegrationTests;

-namespace OpenAIResponse.IntegrationTests;
+namespace ResponseResult.IntegrationTests;

 public class OpenAIResponseStoreTrueChatClientAgentRunTests() : ChatClientAgentRunTests<OpenAIResponseFixture>(() => new(store: true))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";

    [Fact(Skip = SkipReason)]
    public override Task RunWithInstructionsAndNoMessageReturnsExpectedResultAsync() =>
@@ -16,7 +16,7 @@ public class OpenAIResponseStoreTrueChatClientAgentRunTests() : ChatClientAgentR

 public class OpenAIResponseStoreFalseChatClientAgentRunTests() : ChatClientAgentRunTests<OpenAIResponseFixture>(() => new(store: false))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";

    [Fact(Skip = SkipReason)]
    public override Task RunWithInstructionsAndNoMessageReturnsExpectedResultAsync() =>
@@ -12,13 +12,13 @@ using OpenAI;
 using OpenAI.Responses;
 using Shared.IntegrationTests;

-namespace OpenAIResponse.IntegrationTests;
+namespace ResponseResult.IntegrationTests;

 public class OpenAIResponseFixture(bool store) : IChatClientAgentFixture
 {
    private static readonly OpenAIConfiguration s_config = TestConfiguration.LoadSection<OpenAIConfiguration>();

-    private OpenAIResponseClient _openAIResponseClient = null!;
+    private ResponsesClient _openAIResponseClient = null!;
    private ChatClientAgent _agent = null!;

    public AIAgent Agent => this._agent;
@@ -77,7 +77,7 @@ public class OpenAIResponseFixture(bool store) : IChatClientAgentFixture
                    {
                        Instructions = instructions,
                        Tools = aiTools,
-                        RawRepresentationFactory = new Func<IChatClient, object>(_ => new ResponseCreationOptions() { StoredOutputEnabled = store })
+                        RawRepresentationFactory = new Func<IChatClient, object>(_ => new CreateResponseOptions() { StoredOutputEnabled = store })
                    },
                });

@@ -92,7 +92,7 @@ public class OpenAIResponseFixture(bool store) : IChatClientAgentFixture
    public async Task InitializeAsync()
    {
        this._openAIResponseClient = new OpenAIClient(s_config.ApiKey)
-            .GetOpenAIResponseClient(s_config.ChatModelId);
+            .GetResponsesClient(s_config.ChatModelId);

        this._agent = await this.CreateChatClientAgentAsync();
    }
@@ -3,11 +3,11 @@
 using System.Threading.Tasks;
 using AgentConformance.IntegrationTests;

-namespace OpenAIResponse.IntegrationTests;
+namespace ResponseResult.IntegrationTests;

 public class OpenAIResponseStoreTrueRunStreamingTests() : RunStreamingTests<OpenAIResponseFixture>(() => new(store: true))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";
    [Fact(Skip = SkipReason)]
    public override Task RunWithNoMessageDoesNotFailAsync() =>
        Task.CompletedTask;
@@ -15,7 +15,7 @@ public class OpenAIResponseStoreTrueRunStreamingTests() : RunStreamingTests<Open

 public class OpenAIResponseStoreFalseRunStreamingTests() : RunStreamingTests<OpenAIResponseFixture>(() => new(store: false))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";

    [Fact(Skip = SkipReason)]
    public override Task RunWithNoMessageDoesNotFailAsync() =>
@@ -3,11 +3,11 @@
 using System.Threading.Tasks;
 using AgentConformance.IntegrationTests;

-namespace OpenAIResponse.IntegrationTests;
+namespace ResponseResult.IntegrationTests;

 public class OpenAIResponseStoreTrueRunTests() : RunTests<OpenAIResponseFixture>(() => new(store: true))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";
    [Fact(Skip = SkipReason)]
    public override Task RunWithNoMessageDoesNotFailAsync() =>
        Task.CompletedTask;
@@ -15,7 +15,7 @@ public class OpenAIResponseStoreTrueRunTests() : RunTests<OpenAIResponseFixture>

 public class OpenAIResponseStoreFalseRunTests() : RunTests<OpenAIResponseFixture>(() => new(store: false))
 {
-    private const string SkipReason = "OpenAIResponse does not support empty messages";
+    private const string SkipReason = "ResponseResult does not support empty messages";

    [Fact(Skip = SkipReason)]
    public override Task RunWithNoMessageDoesNotFailAsync() =>
@@ -33,7 +33,6 @@ ANTHROPIC_MODEL=""
 OLLAMA_ENDPOINT=""
 OLLAMA_MODEL=""
 # Observability
-ENABLE_OTEL=true
+ENABLE_INSTRUMENTATION=true
 ENABLE_SENSITIVE_DATA=true
-OTLP_ENDPOINT="http://localhost:4317/"
-# APPLICATIONINSIGHTS_CONNECTION_STRING="..."
+OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317/"
@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+### Changed
+
+- **agent-framework-azurefunctions**: Durable Agents: platforms should use consistent entity method names (#2234)
+
+## [1.0.0b251216] - 2025-12-16
+
+### Added
+
+- **agent-framework-ollama**: Ollama connector for Agent Framework (#1104)
+- **agent-framework-core**: Added custom args and thread object to `ai_function` kwargs (#2769)
+- **agent-framework-core**: Enable checkpointing for `WorkflowAgent` (#2774)
+
+### Changed
+
+- **agent-framework-core**: [BREAKING] Observability updates (#2782)
+- **agent-framework-core**: Use agent description in `HandoffBuilder` auto-generated tools (#2714)
+- **agent-framework-core**: Remove warnings from workflow builder when not using factories (#2808)
+
+### Fixed
+
+- **agent-framework-core**: Fix `WorkflowAgent` to include thread conversation history (#2774)
+- **agent-framework-core**: Fix context duplication in handoff workflows when restoring from checkpoint (#2867)
+- **agent-framework-core**: Fix middleware terminate flag to exit function calling loop immediately (#2868)
+- **agent-framework-core**: Fix `WorkflowAgent` to emit `yield_output` as agent response (#2866)
+- **agent-framework-core**: Filter framework kwargs from MCP tool invocations (#2870)
+
 ## [1.0.0b251211] - 2025-12-11

 ### Added
@@ -366,7 +392,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).

-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251211...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251216...HEAD
+[1.0.0b251216]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251211...python-1.0.0b251216
 [1.0.0b251211]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251209...python-1.0.0b251211
 [1.0.0b251209]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251204...python-1.0.0b251209
 [1.0.0b251204]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251120...python-1.0.0b251204
@@ -154,6 +154,14 @@ Example:
 chat_completion = OpenAIChatClient(env_file_path="openai.env")
 ```

+# Method naming inside connectors
+
+When naming methods inside connectors, we have a loose preference for using the following conventions:
+- Use `_prepare_<object>_for_<purpose>` as a prefix for methods that prepare data for sending to the external service.
+- Use `_parse_<object>_from_<source>` as a prefix for methods that process data received from the external service.
+
+This is not a strict rule, but a guideline to help maintain consistency across the codebase.
+
 ## Tests

 All the tests are located in the `tests` folder of each package. There are tests that are marked with a `@skip_if_..._integration_tests_disabled` decorator, these are integration tests that require an external service to be running, like OpenAI or Azure OpenAI.
@@ -5,7 +5,7 @@ import json
 import re
 import uuid
 from collections.abc import AsyncIterable, Sequence
-from typing import Any, cast
+from typing import Any, Final, cast

 import httpx
 from a2a.client import Client, ClientConfig, ClientFactory, minimal_agent_card
@@ -38,6 +38,7 @@ from agent_framework import (
    UriContent,
    prepend_agent_framework_to_user_agent,
 )
+from agent_framework.observability import use_agent_instrumentation

 __all__ = ["A2AAgent"]

@@ -58,6 +59,7 @@ def _get_uri_data(uri: str) -> str:
    return match.group("base64_data")


+@use_agent_instrumentation
 class A2AAgent(BaseAgent):
    """Agent2Agent (A2A) protocol implementation.

@@ -69,6 +71,8 @@ class A2AAgent(BaseAgent):
    Can be initialized with a URL, AgentCard, or existing A2A Client instance.
    """

+    AGENT_PROVIDER_NAME: Final[str] = "A2A"
+
    def __init__(
        self,
        *,
@@ -233,14 +237,14 @@ class A2AAgent(BaseAgent):
            An agent response item.
        """
        messages = self._normalize_messages(messages)
-        a2a_message = self._chat_message_to_a2a_message(messages[-1])
+        a2a_message = self._prepare_message_for_a2a(messages[-1])

        response_stream = self.client.send_message(a2a_message)

        async for item in response_stream:
            if isinstance(item, Message):
                # Process A2A Message
-                contents = self._a2a_parts_to_contents(item.parts)
+                contents = self._parse_contents_from_a2a(item.parts)
                yield AgentRunResponseUpdate(
                    contents=contents,
                    role=Role.ASSISTANT if item.role == A2ARole.agent else Role.USER,
@@ -251,7 +255,7 @@ class A2AAgent(BaseAgent):
                task, _update_event = item
                if isinstance(task, Task) and task.status.state in TERMINAL_TASK_STATES:
                    # Convert Task artifacts to ChatMessages and yield as separate updates
-                    task_messages = self._task_to_chat_messages(task)
+                    task_messages = self._parse_messages_from_task(task)
                    if task_messages:
                        for message in task_messages:
                            # Use the artifact's ID from raw_representation as message_id for unique identification
@@ -276,8 +280,8 @@ class A2AAgent(BaseAgent):
                msg = f"Only Message and Task responses are supported from A2A agents. Received: {type(item)}"
                raise NotImplementedError(msg)

-    def _chat_message_to_a2a_message(self, message: ChatMessage) -> A2AMessage:
-        """Convert a ChatMessage to an A2A Message.
+    def _prepare_message_for_a2a(self, message: ChatMessage) -> A2AMessage:
+        """Prepare a ChatMessage for the A2A protocol.

        Transforms Agent Framework ChatMessage objects into A2A protocol Messages by:
        - Converting all message contents to appropriate A2A Part types
@@ -357,8 +361,8 @@ class A2AAgent(BaseAgent):
            metadata=cast(dict[str, Any], message.additional_properties),
        )

-    def _a2a_parts_to_contents(self, parts: Sequence[A2APart]) -> list[Contents]:
-        """Convert A2A Parts to Agent Framework Contents.
+    def _parse_contents_from_a2a(self, parts: Sequence[A2APart]) -> list[Contents]:
+        """Parse A2A Parts into Agent Framework Contents.

        Transforms A2A protocol Parts into framework-native Content objects,
        handling text, file (URI/bytes), and data parts with metadata preservation.
@@ -406,17 +410,17 @@ class A2AAgent(BaseAgent):
                    raise ValueError(f"Unknown Part kind: {inner_part.kind}")
        return contents

-    def _task_to_chat_messages(self, task: Task) -> list[ChatMessage]:
-        """Convert A2A Task artifacts to ChatMessages with ASSISTANT role."""
+    def _parse_messages_from_task(self, task: Task) -> list[ChatMessage]:
+        """Parse A2A Task artifacts into ChatMessages with ASSISTANT role."""
        messages: list[ChatMessage] = []

        if task.artifacts is not None:
            for artifact in task.artifacts:
-                messages.append(self._artifact_to_chat_message(artifact))
+                messages.append(self._parse_message_from_artifact(artifact))
        elif task.history is not None and len(task.history) > 0:
            # Include the last history item as the agent response
            history_item = task.history[-1]
-            contents = self._a2a_parts_to_contents(history_item.parts)
+            contents = self._parse_contents_from_a2a(history_item.parts)
            messages.append(
                ChatMessage(
                    role=Role.ASSISTANT if history_item.role == A2ARole.agent else Role.USER,
@@ -427,9 +431,9 @@ class A2AAgent(BaseAgent):

        return messages

-    def _artifact_to_chat_message(self, artifact: Artifact) -> ChatMessage:
-        """Convert A2A Artifact to ChatMessage using part contents."""
-        contents = self._a2a_parts_to_contents(artifact.parts)
+    def _parse_message_from_artifact(self, artifact: Artifact) -> ChatMessage:
+        """Parse A2A Artifact into ChatMessage using part contents."""
+        contents = self._parse_contents_from_a2a(artifact.parts)
        return ChatMessage(
            role=Role.ASSISTANT,
            contents=contents,
@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251211"
+version = "1.0.0b251216"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -197,18 +197,18 @@ async def test_run_with_unknown_response_type_raises_error(a2a_agent: A2AAgent,
        await a2a_agent.run("Test message")


-def test_task_to_chat_messages_empty_artifacts(a2a_agent: A2AAgent) -> None:
-    """Test _task_to_chat_messages with task containing no artifacts."""
+def test_parse_messages_from_task_empty_artifacts(a2a_agent: A2AAgent) -> None:
+    """Test _parse_messages_from_task with task containing no artifacts."""
    task = MagicMock()
    task.artifacts = None

-    result = a2a_agent._task_to_chat_messages(task)
+    result = a2a_agent._parse_messages_from_task(task)

    assert len(result) == 0


-def test_task_to_chat_messages_with_artifacts(a2a_agent: A2AAgent) -> None:
-    """Test _task_to_chat_messages with task containing artifacts."""
+def test_parse_messages_from_task_with_artifacts(a2a_agent: A2AAgent) -> None:
+    """Test _parse_messages_from_task with task containing artifacts."""
    task = MagicMock()

    # Create mock artifacts
@@ -232,7 +232,7 @@ def test_task_to_chat_messages_with_artifacts(a2a_agent: A2AAgent) -> None:

    task.artifacts = [artifact1, artifact2]

-    result = a2a_agent._task_to_chat_messages(task)
+    result = a2a_agent._parse_messages_from_task(task)

    assert len(result) == 2
    assert result[0].text == "Content 1"
@@ -240,8 +240,8 @@ def test_task_to_chat_messages_with_artifacts(a2a_agent: A2AAgent) -> None:
    assert all(msg.role == Role.ASSISTANT for msg in result)


-def test_artifact_to_chat_message(a2a_agent: A2AAgent) -> None:
-    """Test _artifact_to_chat_message conversion."""
+def test_parse_message_from_artifact(a2a_agent: A2AAgent) -> None:
+    """Test _parse_message_from_artifact conversion."""
    artifact = MagicMock()
    artifact.artifact_id = "test-artifact"

@@ -253,7 +253,7 @@ def test_artifact_to_chat_message(a2a_agent: A2AAgent) -> None:

    artifact.parts = [text_part]

-    result = a2a_agent._artifact_to_chat_message(artifact)
+    result = a2a_agent._parse_message_from_artifact(artifact)

    assert isinstance(result, ChatMessage)
    assert result.role == Role.ASSISTANT
@@ -276,7 +276,7 @@ def test_get_uri_data_invalid_uri() -> None:
        _get_uri_data("not-a-valid-data-uri")


-def test_a2a_parts_to_contents_conversion(a2a_agent: A2AAgent) -> None:
+def test_parse_contents_from_a2a_conversion(a2a_agent: A2AAgent) -> None:
    """Test A2A parts to contents conversion."""

    agent = A2AAgent(name="Test Agent", client=MockA2AClient(), _http_client=None)
@@ -285,7 +285,7 @@ def test_a2a_parts_to_contents_conversion(a2a_agent: A2AAgent) -> None:
    parts = [Part(root=TextPart(text="First part")), Part(root=TextPart(text="Second part"))]

    # Convert to contents
-    contents = agent._a2a_parts_to_contents(parts)
+    contents = agent._parse_contents_from_a2a(parts)

    # Verify conversion
    assert len(contents) == 2
@@ -295,30 +295,30 @@ def test_a2a_parts_to_contents_conversion(a2a_agent: A2AAgent) -> None:
    assert contents[1].text == "Second part"


-def test_chat_message_to_a2a_message_with_error_content(a2a_agent: A2AAgent) -> None:
-    """Test _chat_message_to_a2a_message with ErrorContent."""
+def test_prepare_message_for_a2a_with_error_content(a2a_agent: A2AAgent) -> None:
+    """Test _prepare_message_for_a2a with ErrorContent."""

    # Create ChatMessage with ErrorContent
    error_content = ErrorContent(message="Test error message")
    message = ChatMessage(role=Role.USER, contents=[error_content])

    # Convert to A2A message
-    a2a_message = a2a_agent._chat_message_to_a2a_message(message)
+    a2a_message = a2a_agent._prepare_message_for_a2a(message)

    # Verify conversion
    assert len(a2a_message.parts) == 1
    assert a2a_message.parts[0].root.text == "Test error message"


-def test_chat_message_to_a2a_message_with_uri_content(a2a_agent: A2AAgent) -> None:
-    """Test _chat_message_to_a2a_message with UriContent."""
+def test_prepare_message_for_a2a_with_uri_content(a2a_agent: A2AAgent) -> None:
+    """Test _prepare_message_for_a2a with UriContent."""

    # Create ChatMessage with UriContent
    uri_content = UriContent(uri="http://example.com/file.pdf", media_type="application/pdf")
    message = ChatMessage(role=Role.USER, contents=[uri_content])

    # Convert to A2A message
-    a2a_message = a2a_agent._chat_message_to_a2a_message(message)
+    a2a_message = a2a_agent._prepare_message_for_a2a(message)

    # Verify conversion
    assert len(a2a_message.parts) == 1
@@ -326,15 +326,15 @@ def test_chat_message_to_a2a_message_with_uri_content(a2a_agent: A2AAgent) -> No
    assert a2a_message.parts[0].root.file.mime_type == "application/pdf"


-def test_chat_message_to_a2a_message_with_data_content(a2a_agent: A2AAgent) -> None:
-    """Test _chat_message_to_a2a_message with DataContent."""
+def test_prepare_message_for_a2a_with_data_content(a2a_agent: A2AAgent) -> None:
+    """Test _prepare_message_for_a2a with DataContent."""

    # Create ChatMessage with DataContent (base64 data URI)
    data_content = DataContent(uri="data:text/plain;base64,SGVsbG8gV29ybGQ=", media_type="text/plain")
    message = ChatMessage(role=Role.USER, contents=[data_content])

    # Convert to A2A message
-    a2a_message = a2a_agent._chat_message_to_a2a_message(message)
+    a2a_message = a2a_agent._prepare_message_for_a2a(message)

    # Verify conversion
    assert len(a2a_message.parts) == 1
@@ -342,14 +342,14 @@ def test_chat_message_to_a2a_message_with_data_content(a2a_agent: A2AAgent) -> N
    assert a2a_message.parts[0].root.file.mime_type == "text/plain"


-def test_chat_message_to_a2a_message_empty_contents_raises_error(a2a_agent: A2AAgent) -> None:
-    """Test _chat_message_to_a2a_message with empty contents raises ValueError."""
+def test_prepare_message_for_a2a_empty_contents_raises_error(a2a_agent: A2AAgent) -> None:
+    """Test _prepare_message_for_a2a with empty contents raises ValueError."""
    # Create ChatMessage with no contents
    message = ChatMessage(role=Role.USER, contents=[])

    # Should raise ValueError for empty contents
    with raises(ValueError, match="ChatMessage.contents is empty"):
-        a2a_agent._chat_message_to_a2a_message(message)
+        a2a_agent._prepare_message_for_a2a(message)


 async def test_run_stream_with_message_response(a2a_agent: A2AAgent, mock_a2a_client: MockA2AClient) -> None:
@@ -405,7 +405,7 @@ async def test_context_manager_no_cleanup_when_no_http_client() -> None:
        pass


-def test_chat_message_to_a2a_message_with_multiple_contents() -> None:
+def test_prepare_message_for_a2a_with_multiple_contents() -> None:
    """Test conversion of ChatMessage with multiple contents."""

    agent = A2AAgent(client=MagicMock(), _http_client=None)
@@ -421,7 +421,7 @@ def test_chat_message_to_a2a_message_with_multiple_contents() -> None:
        ],
    )

-    result = agent._chat_message_to_a2a_message(message)
+    result = agent._prepare_message_for_a2a(message)

    # Should have converted all 4 contents to parts
    assert len(result.parts) == 4
@@ -433,7 +433,7 @@ def test_chat_message_to_a2a_message_with_multiple_contents() -> None:
    assert result.parts[3].root.kind == "text"  # JSON text remains as text (no parsing)


-def test_a2a_parts_to_contents_with_data_part() -> None:
+def test_parse_contents_from_a2a_with_data_part() -> None:
    """Test conversion of A2A DataPart."""

    agent = A2AAgent(client=MagicMock(), _http_client=None)
@@ -441,7 +441,7 @@ def test_a2a_parts_to_contents_with_data_part() -> None:
    # Create DataPart
    data_part = Part(root=DataPart(data={"key": "value", "number": 42}, metadata={"source": "test"}))

-    contents = agent._a2a_parts_to_contents([data_part])
+    contents = agent._parse_contents_from_a2a([data_part])

    assert len(contents) == 1

@@ -450,7 +450,7 @@ def test_a2a_parts_to_contents_with_data_part() -> None:
    assert contents[0].additional_properties == {"source": "test"}


-def test_a2a_parts_to_contents_unknown_part_kind() -> None:
+def test_parse_contents_from_a2a_unknown_part_kind() -> None:
    """Test error handling for unknown A2A part kind."""
    agent = A2AAgent(client=MagicMock(), _http_client=None)

@@ -459,10 +459,10 @@ def test_a2a_parts_to_contents_unknown_part_kind() -> None:
    mock_part.root.kind = "unknown_kind"

    with raises(ValueError, match="Unknown Part kind: unknown_kind"):
-        agent._a2a_parts_to_contents([mock_part])
+        agent._parse_contents_from_a2a([mock_part])


-def test_chat_message_to_a2a_message_with_hosted_file() -> None:
+def test_prepare_message_for_a2a_with_hosted_file() -> None:
    """Test conversion of ChatMessage with HostedFileContent to A2A message."""

    agent = A2AAgent(client=MagicMock(), _http_client=None)
@@ -473,7 +473,7 @@ def test_chat_message_to_a2a_message_with_hosted_file() -> None:
        contents=[HostedFileContent(file_id="hosted://storage/document.pdf")],
    )

-    result = agent._chat_message_to_a2a_message(message)  # noqa: SLF001
+    result = agent._prepare_message_for_a2a(message)  # noqa: SLF001

    # Verify the conversion
    assert len(result.parts) == 1
@@ -488,7 +488,7 @@ def test_chat_message_to_a2a_message_with_hosted_file() -> None:
    assert part.root.file.mime_type is None  # HostedFileContent doesn't specify media_type


-def test_a2a_parts_to_contents_with_hosted_file_uri() -> None:
+def test_parse_contents_from_a2a_with_hosted_file_uri() -> None:
    """Test conversion of A2A FilePart with hosted file URI back to UriContent."""

    agent = A2AAgent(client=MagicMock(), _http_client=None)
@@ -503,7 +503,7 @@ def test_a2a_parts_to_contents_with_hosted_file_uri() -> None:
        )
    )

-    contents = agent._a2a_parts_to_contents([file_part])  # noqa: SLF001
+    contents = agent._parse_contents_from_a2a([file_part])  # noqa: SLF001

    assert len(contents) == 1

@@ -23,7 +23,7 @@ from agent_framework import (
 from agent_framework._middleware import use_chat_middleware
 from agent_framework._tools import use_function_invocation
 from agent_framework._types import BaseContent, Contents
-from agent_framework.observability import use_observability
+from agent_framework.observability import use_instrumentation

 from ._event_converters import AGUIEventConverter
 from ._http_service import AGUIHttpService
@@ -89,7 +89,7 @@ def _apply_server_function_call_unwrap(chat_client: TBaseChatClient) -> TBaseCha

@_apply_server_function_call_unwrap
@use_function_invocation
-@use_observability
+@use_instrumentation
@use_chat_middleware
 class AGUIChatClient(BaseChatClient):
    """Chat client for communicating with AG-UI compliant servers.
@@ -86,7 +86,7 @@ class ExecutionContext:
    def run_id(self) -> str:
        """Get or generate run ID."""
        if self._run_id is None:
-            self._run_id = self.input_data.get("run_id") or str(uuid.uuid4())
+            self._run_id = self.input_data.get("run_id") or self.input_data.get("runId") or str(uuid.uuid4())
        # This should never be None after the if block above, but satisfy type checkers
        if self._run_id is None:  # pragma: no cover
            raise RuntimeError("Failed to initialize run_id")
@@ -96,7 +96,7 @@ class ExecutionContext:
    def thread_id(self) -> str:
        """Get or generate thread ID."""
        if self._thread_id is None:
-            self._thread_id = self.input_data.get("thread_id") or str(uuid.uuid4())
+            self._thread_id = self.input_data.get("thread_id") or self.input_data.get("threadId") or str(uuid.uuid4())
        # This should never be None after the if block above, but satisfy type checkers
        if self._thread_id is None:  # pragma: no cover
            raise RuntimeError("Failed to initialize thread_id")
@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b251211"
+version = "1.0.0b251216"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -83,3 +83,71 @@ async def test_default_orchestrator_merges_client_tools() -> None:
    assert "server_tool" in tool_names
    assert "get_weather" in tool_names
    assert agent.chat_client.function_invocation_configuration.additional_tools
+
+
+async def test_default_orchestrator_with_camel_case_ids() -> None:
+    """Client tool is able to extract camelCase IDs."""
+
+    agent = DummyAgent()
+    orchestrator = DefaultOrchestrator()
+
+    input_data = {
+        "runId": "test-camelcase-runid",
+        "threadId": "test-camelcase-threadid",
+        "messages": [
+            {
+                "role": "user",
+                "content": [{"type": "input_text", "text": "Hello"}],
+            }
+        ],
+        "tools": [],
+    }
+
+    context = ExecutionContext(
+        input_data=input_data,
+        agent=agent,
+        config=AgentConfig(),
+    )
+
+    events = []
+    async for event in orchestrator.run(context):
+        events.append(event)
+
+    # assert the last event has the expected run_id and thread_id
+    last_event = events[-1]
+    assert last_event.run_id == "test-camelcase-runid"
+    assert last_event.thread_id == "test-camelcase-threadid"
+
+
+async def test_default_orchestrator_with_snake_case_ids() -> None:
+    """Client tool is able to extract snake_case IDs."""
+
+    agent = DummyAgent()
+    orchestrator = DefaultOrchestrator()
+
+    input_data = {
+        "run_id": "test-snakecase-runid",
+        "thread_id": "test-snakecase-threadid",
+        "messages": [
+            {
+                "role": "user",
+                "content": [{"type": "input_text", "text": "Hello"}],
+            }
+        ],
+        "tools": [],
+    }
+
+    context = ExecutionContext(
+        input_data=input_data,
+        agent=agent,
+        config=AgentConfig(),
+    )
+
+    events = []
+    async for event in orchestrator.run(context):
+        events.append(event)
+
+    # assert the last event has the expected run_id and thread_id
+    last_event = events[-1]
+    assert last_event.run_id == "test-snakecase-runid"
+    assert last_event.thread_id == "test-snakecase-threadid"
@@ -25,7 +25,6 @@ from agent_framework import (
    TextContent,
    TextReasoningContent,
    TextSpanRegion,
-    ToolProtocol,
    UsageContent,
    UsageDetails,
    get_logger,
@@ -35,7 +34,7 @@ from agent_framework import (
 )
 from agent_framework._pydantic import AFBaseSettings
 from agent_framework.exceptions import ServiceInitializationError
-from agent_framework.observability import use_observability
+from agent_framework.observability import use_instrumentation
 from anthropic import AsyncAnthropic
 from anthropic.types.beta import (
    BetaContentBlock,
@@ -110,7 +109,7 @@ TAnthropicClient = TypeVar("TAnthropicClient", bound="AnthropicClient")


@use_function_invocation
-@use_observability
+@use_instrumentation
@use_chat_middleware
 class AnthropicClient(BaseChatClient):
    """Anthropic Chat client."""
@@ -214,9 +213,11 @@ class AnthropicClient(BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> ChatResponse:
-        # Extract necessary state from messages and options
-        run_options = self._create_run_options(messages, chat_options, **kwargs)
+        # prepare
+        run_options = self._prepare_options(messages, chat_options, **kwargs)
+        # execute
        message = await self.anthropic_client.beta.messages.create(**run_options, stream=False)
+        # process
        return self._process_message(message)

    async def _inner_get_streaming_response(
@@ -226,16 +227,17 @@ class AnthropicClient(BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> AsyncIterable[ChatResponseUpdate]:
-        # Extract necessary state from messages and options
-        run_options = self._create_run_options(messages, chat_options, **kwargs)
+        # prepare
+        run_options = self._prepare_options(messages, chat_options, **kwargs)
+        # execute and process
        async for chunk in await self.anthropic_client.beta.messages.create(**run_options, stream=True):
            parsed_chunk = self._process_stream_event(chunk)
            if parsed_chunk:
                yield parsed_chunk

-    # region Create Run Options and Helpers
+    # region Prep methods

-    def _create_run_options(
+    def _prepare_options(
        self,
        messages: MutableSequence[ChatMessage],
        chat_options: ChatOptions,
@@ -251,78 +253,91 @@ class AnthropicClient(BaseChatClient):
        Returns:
            A dictionary of run options for the Anthropic client.
        """
-        if chat_options.additional_properties and "additional_beta_flags" in chat_options.additional_properties:
-            betas = chat_options.additional_properties.pop("additional_beta_flags")
-        else:
-            betas = []
-        run_options: dict[str, Any] = {
-            "model": chat_options.model_id or self.model_id,
-            "messages": self._convert_messages_to_anthropic_format(messages),
-            "max_tokens": chat_options.max_tokens or ANTHROPIC_DEFAULT_MAX_TOKENS,
-            "extra_headers": {"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
-            "betas": {*BETA_FLAGS, *self.additional_beta_flags, *betas},
-        }
+        run_options: dict[str, Any] = chat_options.to_dict(
+            exclude={
+                "type",
+                "instructions",  # handled via system message
+                "tool_choice",  # handled separately
+                "allow_multiple_tool_calls",  # handled via tool_choice
+                "additional_properties",  # handled separately
+            }
+        )

-        # Add any additional options from chat_options or kwargs
-        if chat_options.temperature is not None:
-            run_options["temperature"] = chat_options.temperature
-        if chat_options.top_p is not None:
-            run_options["top_p"] = chat_options.top_p
-        if chat_options.stop is not None:
-            run_options["stop_sequences"] = chat_options.stop
+        # translations between ChatOptions and Anthropic API
+        translations = {
+            "model_id": "model",
+            "stop": "stop_sequences",
+        }
+        for old_key, new_key in translations.items():
+            if old_key in run_options and old_key != new_key:
+                run_options[new_key] = run_options.pop(old_key)
+
+        # model id
+        if not run_options.get("model"):
+            if not self.model_id:
+                raise ValueError("model_id must be a non-empty string")
+            run_options["model"] = self.model_id
+
+        # max_tokens - Anthropic requires this, default if not provided
+        if not run_options.get("max_tokens"):
+            run_options["max_tokens"] = ANTHROPIC_DEFAULT_MAX_TOKENS
+
+        # messages
+        run_options["messages"] = self._prepare_messages_for_anthropic(messages)
+
+        # system message - first system message is passed as instructions
        if messages and isinstance(messages[0], ChatMessage) and messages[0].role == Role.SYSTEM:
-            # first system message is passed as instructions
            run_options["system"] = messages[0].text
-        if chat_options.tool_choice is not None:
-            match (
-                chat_options.tool_choice if isinstance(chat_options.tool_choice, str) else chat_options.tool_choice.mode
-            ):
-                case "auto":
-                    run_options["tool_choice"] = {"type": "auto"}
-                    if chat_options.allow_multiple_tool_calls is not None:
-                        run_options["tool_choice"][  # type:ignore[reportArgumentType]
-                            "disable_parallel_tool_use"
-                        ] = not chat_options.allow_multiple_tool_calls
-                case "required":
-                    if chat_options.tool_choice.required_function_name:
-                        run_options["tool_choice"] = {
-                            "type": "tool",
-                            "name": chat_options.tool_choice.required_function_name,
-                        }
-                        if chat_options.allow_multiple_tool_calls is not None:
-                            run_options["tool_choice"][  # type:ignore[reportArgumentType]
-                                "disable_parallel_tool_use"
-                            ] = not chat_options.allow_multiple_tool_calls
-                    else:
-                        run_options["tool_choice"] = {"type": "any"}
-                        if chat_options.allow_multiple_tool_calls is not None:
-                            run_options["tool_choice"][  # type:ignore[reportArgumentType]
-                                "disable_parallel_tool_use"
-                            ] = not chat_options.allow_multiple_tool_calls
-                case "none":
-                    run_options["tool_choice"] = {"type": "none"}
-                case _:
-                    logger.debug(f"Ignoring unsupported tool choice mode: {chat_options.tool_choice.mode} for now")
-        if tools_and_mcp := self._convert_tools_to_anthropic_format(chat_options.tools):
-            run_options.update(tools_and_mcp)
-        if chat_options.additional_properties:
-            run_options.update(chat_options.additional_properties)
+
+        # betas
+        run_options["betas"] = self._prepare_betas(chat_options)
+
+        # extra headers
+        run_options["extra_headers"] = {"User-Agent": AGENT_FRAMEWORK_USER_AGENT}
+
+        # tools, mcp servers and tool choice
+        if tools_config := self._prepare_tools_for_anthropic(chat_options):
+            run_options.update(tools_config)
+
+        # additional properties
+        additional_options = {
+            key: value
+            for key, value in chat_options.additional_properties.items()
+            if value is not None and key != "additional_beta_flags"
+        }
+        if additional_options:
+            run_options.update(additional_options)
        run_options.update(kwargs)
        return run_options

-    def _convert_messages_to_anthropic_format(self, messages: MutableSequence[ChatMessage]) -> list[dict[str, Any]]:
-        """Convert a list of ChatMessages to the format expected by the Anthropic client.
+    def _prepare_betas(self, chat_options: ChatOptions) -> set[str]:
+        """Prepare the beta flags for the Anthropic API request.
+
+        Args:
+            chat_options: The chat options that may contain additional beta flags.
+
+        Returns:
+            A set of beta flag strings to include in the request.
+        """
+        return {
+            *BETA_FLAGS,
+            *self.additional_beta_flags,
+            *chat_options.additional_properties.get("additional_beta_flags", []),
+        }
+
+    def _prepare_messages_for_anthropic(self, messages: MutableSequence[ChatMessage]) -> list[dict[str, Any]]:
+        """Prepare a list of ChatMessages for the Anthropic client.

        This skips the first message if it is a system message,
        as Anthropic expects system instructions as a separate parameter.
        """
        # first system message is passed as instructions
        if messages and isinstance(messages[0], ChatMessage) and messages[0].role == Role.SYSTEM:
-            return [self._convert_message_to_anthropic_format(msg) for msg in messages[1:]]
-        return [self._convert_message_to_anthropic_format(msg) for msg in messages]
+            return [self._prepare_message_for_anthropic(msg) for msg in messages[1:]]
+        return [self._prepare_message_for_anthropic(msg) for msg in messages]

-    def _convert_message_to_anthropic_format(self, message: ChatMessage) -> dict[str, Any]:
-        """Convert a ChatMessage to the format expected by the Anthropic client.
+    def _prepare_message_for_anthropic(self, message: ChatMessage) -> dict[str, Any]:
+        """Prepare a ChatMessage for the Anthropic client.

        Args:
            message: The ChatMessage to convert.
@@ -376,58 +391,96 @@ class AnthropicClient(BaseChatClient):
            "content": a_content,
        }

-    def _convert_tools_to_anthropic_format(
-        self, tools: list[ToolProtocol | MutableMapping[str, Any]] | None
-    ) -> dict[str, Any] | None:
-        if not tools:
-            return None
-        tool_list: list[MutableMapping[str, Any]] = []
-        mcp_server_list: list[MutableMapping[str, Any]] = []
-        for tool in tools:
-            match tool:
-                case MutableMapping():
-                    tool_list.append(tool)
-                case AIFunction():
-                    tool_list.append({
-                        "type": "custom",
-                        "name": tool.name,
-                        "description": tool.description,
-                        "input_schema": tool.parameters(),
-                    })
-                case HostedWebSearchTool():
-                    search_tool: dict[str, Any] = {
-                        "type": "web_search_20250305",
-                        "name": "web_search",
-                    }
-                    if tool.additional_properties:
-                        search_tool.update(tool.additional_properties)
-                    tool_list.append(search_tool)
-                case HostedCodeInterpreterTool():
-                    code_tool: dict[str, Any] = {
-                        "type": "code_execution_20250825",
-                        "name": "code_execution",
-                    }
-                    tool_list.append(code_tool)
-                case HostedMCPTool():
-                    server_def: dict[str, Any] = {
-                        "type": "url",
-                        "name": tool.name,
-                        "url": str(tool.url),
-                    }
-                    if tool.allowed_tools:
-                        server_def["tool_configuration"] = {"allowed_tools": list(tool.allowed_tools)}
-                    if tool.headers and (auth := tool.headers.get("authorization")):
-                        server_def["authorization_token"] = auth
-                    mcp_server_list.append(server_def)
-                case _:
-                    logger.debug(f"Ignoring unsupported tool type: {type(tool)} for now")
+    def _prepare_tools_for_anthropic(self, chat_options: ChatOptions) -> dict[str, Any] | None:
+        """Prepare tools and tool choice configuration for the Anthropic API request.

-        all_tools: dict[str, list[MutableMapping[str, Any]]] = {}
-        if tool_list:
-            all_tools["tools"] = tool_list
-        if mcp_server_list:
-            all_tools["mcp_servers"] = mcp_server_list
-        return all_tools
+        Args:
+            chat_options: The chat options containing tools and tool choice settings.
+
+        Returns:
+            A dictionary with tools, mcp_servers, and tool_choice configuration, or None if empty.
+        """
+        result: dict[str, Any] = {}
+
+        # Process tools
+        if chat_options.tools:
+            tool_list: list[MutableMapping[str, Any]] = []
+            mcp_server_list: list[MutableMapping[str, Any]] = []
+            for tool in chat_options.tools:
+                match tool:
+                    case MutableMapping():
+                        tool_list.append(tool)
+                    case AIFunction():
+                        tool_list.append({
+                            "type": "custom",
+                            "name": tool.name,
+                            "description": tool.description,
+                            "input_schema": tool.parameters(),
+                        })
+                    case HostedWebSearchTool():
+                        search_tool: dict[str, Any] = {
+                            "type": "web_search_20250305",
+                            "name": "web_search",
+                        }
+                        if tool.additional_properties:
+                            search_tool.update(tool.additional_properties)
+                        tool_list.append(search_tool)
+                    case HostedCodeInterpreterTool():
+                        code_tool: dict[str, Any] = {
+                            "type": "code_execution_20250825",
+                            "name": "code_execution",
+                        }
+                        tool_list.append(code_tool)
+                    case HostedMCPTool():
+                        server_def: dict[str, Any] = {
+                            "type": "url",
+                            "name": tool.name,
+                            "url": str(tool.url),
+                        }
+                        if tool.allowed_tools:
+                            server_def["tool_configuration"] = {"allowed_tools": list(tool.allowed_tools)}
+                        if tool.headers and (auth := tool.headers.get("authorization")):
+                            server_def["authorization_token"] = auth
+                        mcp_server_list.append(server_def)
+                    case _:
+                        logger.debug(f"Ignoring unsupported tool type: {type(tool)} for now")
+
+            if tool_list:
+                result["tools"] = tool_list
+            if mcp_server_list:
+                result["mcp_servers"] = mcp_server_list
+
+        # Process tool choice
+        if chat_options.tool_choice is not None:
+            tool_choice_mode = (
+                chat_options.tool_choice if isinstance(chat_options.tool_choice, str) else chat_options.tool_choice.mode
+            )
+            match tool_choice_mode:
+                case "auto":
+                    tool_choice: dict[str, Any] = {"type": "auto"}
+                    if chat_options.allow_multiple_tool_calls is not None:
+                        tool_choice["disable_parallel_tool_use"] = not chat_options.allow_multiple_tool_calls
+                    result["tool_choice"] = tool_choice
+                case "required":
+                    if (
+                        not isinstance(chat_options.tool_choice, str)
+                        and chat_options.tool_choice.required_function_name
+                    ):
+                        tool_choice = {
+                            "type": "tool",
+                            "name": chat_options.tool_choice.required_function_name,
+                        }
+                    else:
+                        tool_choice = {"type": "any"}
+                    if chat_options.allow_multiple_tool_calls is not None:
+                        tool_choice["disable_parallel_tool_use"] = not chat_options.allow_multiple_tool_calls
+                    result["tool_choice"] = tool_choice
+                case "none":
+                    result["tool_choice"] = {"type": "none"}
+                case _:
+                    logger.debug(f"Ignoring unsupported tool choice mode: {tool_choice_mode} for now")
+
+        return result or None

    # region Response Processing Methods

@@ -445,11 +498,11 @@ class AnthropicClient(BaseChatClient):
            messages=[
                ChatMessage(
                    role=Role.ASSISTANT,
-                    contents=self._parse_message_contents(message.content),
+                    contents=self._parse_contents_from_anthropic(message.content),
                    raw_representation=message,
                )
            ],
-            usage_details=self._parse_message_usage(message.usage),
+            usage_details=self._parse_usage_from_anthropic(message.usage),
            model_id=message.model,
            finish_reason=FINISH_REASON_MAP.get(message.stop_reason) if message.stop_reason else None,
            raw_response=message,
@@ -467,12 +520,12 @@ class AnthropicClient(BaseChatClient):
        match event.type:
            case "message_start":
                usage_details: list[UsageContent] = []
-                if event.message.usage and (details := self._parse_message_usage(event.message.usage)):
+                if event.message.usage and (details := self._parse_usage_from_anthropic(event.message.usage)):
                    usage_details.append(UsageContent(details=details))

                return ChatResponseUpdate(
                    response_id=event.message.id,
-                    contents=[*self._parse_message_contents(event.message.content), *usage_details],
+                    contents=[*self._parse_contents_from_anthropic(event.message.content), *usage_details],
                    model_id=event.message.model,
                    finish_reason=FINISH_REASON_MAP.get(event.message.stop_reason)
                    if event.message.stop_reason
@@ -480,7 +533,7 @@ class AnthropicClient(BaseChatClient):
                    raw_response=event,
                )
            case "message_delta":
-                usage = self._parse_message_usage(event.usage)
+                usage = self._parse_usage_from_anthropic(event.usage)
                return ChatResponseUpdate(
                    contents=[UsageContent(details=usage, raw_representation=event.usage)] if usage else [],
                    raw_response=event,
@@ -488,13 +541,13 @@ class AnthropicClient(BaseChatClient):
            case "message_stop":
                logger.debug("Received message_stop event; no content to process.")
            case "content_block_start":
-                contents = self._parse_message_contents([event.content_block])
+                contents = self._parse_contents_from_anthropic([event.content_block])
                return ChatResponseUpdate(
                    contents=contents,
                    raw_response=event,
                )
            case "content_block_delta":
-                contents = self._parse_message_contents([event.delta])
+                contents = self._parse_contents_from_anthropic([event.delta])
                return ChatResponseUpdate(
                    contents=contents,
                    raw_response=event,
@@ -505,7 +558,7 @@ class AnthropicClient(BaseChatClient):
                logger.debug(f"Ignoring unsupported event type: {event.type}")
        return None

-    def _parse_message_usage(self, usage: BetaUsage | BetaMessageDeltaUsage | None) -> UsageDetails | None:
+    def _parse_usage_from_anthropic(self, usage: BetaUsage | BetaMessageDeltaUsage | None) -> UsageDetails | None:
        """Parse usage details from the Anthropic message usage."""
        if not usage:
            return None
@@ -518,7 +571,7 @@ class AnthropicClient(BaseChatClient):
            usage_details.additional_counts["anthropic.cache_read_input_tokens"] = usage.cache_read_input_tokens
        return usage_details

-    def _parse_message_contents(
+    def _parse_contents_from_anthropic(
        self, content: Sequence[BetaContentBlock | BetaRawContentBlockDelta | BetaTextBlock]
    ) -> list[Contents]:
        """Parse contents from the Anthropic message."""
@@ -530,7 +583,7 @@ class AnthropicClient(BaseChatClient):
                        TextContent(
                            text=content_block.text,
                            raw_representation=content_block,
-                            annotations=self._parse_citations(content_block),
+                            annotations=self._parse_citations_from_anthropic(content_block),
                        )
                    )
                case "tool_use" | "mcp_tool_use" | "server_tool_use":
@@ -549,7 +602,7 @@ class AnthropicClient(BaseChatClient):
                        FunctionResultContent(
                            call_id=content_block.tool_use_id,
                            name=name if name and call_id == content_block.tool_use_id else "mcp_tool",
-                            result=self._parse_message_contents(content_block.content)
+                            result=self._parse_contents_from_anthropic(content_block.content)
                            if isinstance(content_block.content, list)
                            else content_block.content,
                            raw_representation=content_block,
@@ -608,7 +661,7 @@ class AnthropicClient(BaseChatClient):
                    logger.debug(f"Ignoring unsupported content type: {content_block.type} for now")
        return contents

-    def _parse_citations(
+    def _parse_citations_from_anthropic(
        self, content_block: BetaContentBlock | BetaRawContentBlockDelta | BetaTextBlock
    ) -> list[Annotations] | None:
        content_citations = getattr(content_block, "citations", None)
@@ -4,7 +4,7 @@ description = "Anthropic integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251211"
+version = "1.0.0b251216"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -151,12 +151,12 @@ def test_anthropic_client_service_url(mock_anthropic_client: MagicMock) -> None:
 # Message Conversion Tests


-def test_convert_message_to_anthropic_format_text(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_message_for_anthropic_text(mock_anthropic_client: MagicMock) -> None:
    """Test converting text message to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
    message = ChatMessage(role=Role.USER, text="Hello, world!")

-    result = chat_client._convert_message_to_anthropic_format(message)
+    result = chat_client._prepare_message_for_anthropic(message)

    assert result["role"] == "user"
    assert len(result["content"]) == 1
@@ -164,7 +164,7 @@ def test_convert_message_to_anthropic_format_text(mock_anthropic_client: MagicMo
    assert result["content"][0]["text"] == "Hello, world!"


-def test_convert_message_to_anthropic_format_function_call(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_message_for_anthropic_function_call(mock_anthropic_client: MagicMock) -> None:
    """Test converting function call message to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
    message = ChatMessage(
@@ -178,7 +178,7 @@ def test_convert_message_to_anthropic_format_function_call(mock_anthropic_client
        ],
    )

-    result = chat_client._convert_message_to_anthropic_format(message)
+    result = chat_client._prepare_message_for_anthropic(message)

    assert result["role"] == "assistant"
    assert len(result["content"]) == 1
@@ -188,7 +188,7 @@ def test_convert_message_to_anthropic_format_function_call(mock_anthropic_client
    assert result["content"][0]["input"] == {"location": "San Francisco"}


-def test_convert_message_to_anthropic_format_function_result(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_message_for_anthropic_function_result(mock_anthropic_client: MagicMock) -> None:
    """Test converting function result message to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
    message = ChatMessage(
@@ -202,7 +202,7 @@ def test_convert_message_to_anthropic_format_function_result(mock_anthropic_clie
        ],
    )

-    result = chat_client._convert_message_to_anthropic_format(message)
+    result = chat_client._prepare_message_for_anthropic(message)

    assert result["role"] == "user"
    assert len(result["content"]) == 1
@@ -214,7 +214,7 @@ def test_convert_message_to_anthropic_format_function_result(mock_anthropic_clie
    assert result["content"][0]["is_error"] is False


-def test_convert_message_to_anthropic_format_text_reasoning(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_message_for_anthropic_text_reasoning(mock_anthropic_client: MagicMock) -> None:
    """Test converting text reasoning message to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
    message = ChatMessage(
@@ -222,7 +222,7 @@ def test_convert_message_to_anthropic_format_text_reasoning(mock_anthropic_clien
        contents=[TextReasoningContent(text="Let me think about this...")],
    )

-    result = chat_client._convert_message_to_anthropic_format(message)
+    result = chat_client._prepare_message_for_anthropic(message)

    assert result["role"] == "assistant"
    assert len(result["content"]) == 1
@@ -230,7 +230,7 @@ def test_convert_message_to_anthropic_format_text_reasoning(mock_anthropic_clien
    assert result["content"][0]["thinking"] == "Let me think about this..."


-def test_convert_messages_to_anthropic_format_with_system(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_messages_for_anthropic_with_system(mock_anthropic_client: MagicMock) -> None:
    """Test converting messages list with system message."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
    messages = [
@@ -238,7 +238,7 @@ def test_convert_messages_to_anthropic_format_with_system(mock_anthropic_client:
        ChatMessage(role=Role.USER, text="Hello!"),
    ]

-    result = chat_client._convert_messages_to_anthropic_format(messages)
+    result = chat_client._prepare_messages_for_anthropic(messages)

    # System message should be skipped
    assert len(result) == 1
@@ -246,7 +246,7 @@ def test_convert_messages_to_anthropic_format_with_system(mock_anthropic_client:
    assert result[0]["content"][0]["text"] == "Hello!"


-def test_convert_messages_to_anthropic_format_without_system(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_messages_for_anthropic_without_system(mock_anthropic_client: MagicMock) -> None:
    """Test converting messages list without system message."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
    messages = [
@@ -254,7 +254,7 @@ def test_convert_messages_to_anthropic_format_without_system(mock_anthropic_clie
        ChatMessage(role=Role.ASSISTANT, text="Hi there!"),
    ]

-    result = chat_client._convert_messages_to_anthropic_format(messages)
+    result = chat_client._prepare_messages_for_anthropic(messages)

    assert len(result) == 2
    assert result[0]["role"] == "user"
@@ -264,7 +264,7 @@ def test_convert_messages_to_anthropic_format_without_system(mock_anthropic_clie
 # Tool Conversion Tests


-def test_convert_tools_to_anthropic_format_ai_function(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_ai_function(mock_anthropic_client: MagicMock) -> None:
    """Test converting AIFunction to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

@@ -273,9 +273,8 @@ def test_convert_tools_to_anthropic_format_ai_function(mock_anthropic_client: Ma
        """Get weather for a location."""
        return f"Weather for {location}"

-    tools = [get_weather]
-
-    result = chat_client._convert_tools_to_anthropic_format(tools)
+    chat_options = ChatOptions(tools=[get_weather])
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is not None
    assert "tools" in result
@@ -285,12 +284,12 @@ def test_convert_tools_to_anthropic_format_ai_function(mock_anthropic_client: Ma
    assert "Get weather for a location" in result["tools"][0]["description"]


-def test_convert_tools_to_anthropic_format_web_search(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_web_search(mock_anthropic_client: MagicMock) -> None:
    """Test converting HostedWebSearchTool to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
-    tools = [HostedWebSearchTool()]
+    chat_options = ChatOptions(tools=[HostedWebSearchTool()])

-    result = chat_client._convert_tools_to_anthropic_format(tools)
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is not None
    assert "tools" in result
@@ -299,12 +298,12 @@ def test_convert_tools_to_anthropic_format_web_search(mock_anthropic_client: Mag
    assert result["tools"][0]["name"] == "web_search"


-def test_convert_tools_to_anthropic_format_code_interpreter(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_code_interpreter(mock_anthropic_client: MagicMock) -> None:
    """Test converting HostedCodeInterpreterTool to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
-    tools = [HostedCodeInterpreterTool()]
+    chat_options = ChatOptions(tools=[HostedCodeInterpreterTool()])

-    result = chat_client._convert_tools_to_anthropic_format(tools)
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is not None
    assert "tools" in result
@@ -313,12 +312,12 @@ def test_convert_tools_to_anthropic_format_code_interpreter(mock_anthropic_clien
    assert result["tools"][0]["name"] == "code_execution"


-def test_convert_tools_to_anthropic_format_mcp_tool(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_mcp_tool(mock_anthropic_client: MagicMock) -> None:
    """Test converting HostedMCPTool to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
-    tools = [HostedMCPTool(name="test-mcp", url="https://example.com/mcp")]
+    chat_options = ChatOptions(tools=[HostedMCPTool(name="test-mcp", url="https://example.com/mcp")])

-    result = chat_client._convert_tools_to_anthropic_format(tools)
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is not None
    assert "mcp_servers" in result
@@ -328,18 +327,20 @@ def test_convert_tools_to_anthropic_format_mcp_tool(mock_anthropic_client: Magic
    assert result["mcp_servers"][0]["url"] == "https://example.com/mcp"


-def test_convert_tools_to_anthropic_format_mcp_with_auth(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_mcp_with_auth(mock_anthropic_client: MagicMock) -> None:
    """Test converting HostedMCPTool with authorization headers."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
-    tools = [
-        HostedMCPTool(
-            name="test-mcp",
-            url="https://example.com/mcp",
-            headers={"authorization": "Bearer token123"},
-        )
-    ]
+    chat_options = ChatOptions(
+        tools=[
+            HostedMCPTool(
+                name="test-mcp",
+                url="https://example.com/mcp",
+                headers={"authorization": "Bearer token123"},
+            )
+        ]
+    )

-    result = chat_client._convert_tools_to_anthropic_format(tools)
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is not None
    assert "mcp_servers" in result
@@ -348,12 +349,12 @@ def test_convert_tools_to_anthropic_format_mcp_with_auth(mock_anthropic_client:
    assert result["mcp_servers"][0]["authorization_token"] == "Bearer token123"


-def test_convert_tools_to_anthropic_format_dict_tool(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_dict_tool(mock_anthropic_client: MagicMock) -> None:
    """Test converting dict tool to Anthropic format."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
-    tools = [{"type": "custom", "name": "custom_tool", "description": "A custom tool"}]
+    chat_options = ChatOptions(tools=[{"type": "custom", "name": "custom_tool", "description": "A custom tool"}])

-    result = chat_client._convert_tools_to_anthropic_format(tools)
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is not None
    assert "tools" in result
@@ -361,11 +362,12 @@ def test_convert_tools_to_anthropic_format_dict_tool(mock_anthropic_client: Magi
    assert result["tools"][0]["name"] == "custom_tool"


-def test_convert_tools_to_anthropic_format_none(mock_anthropic_client: MagicMock) -> None:
+def test_prepare_tools_for_anthropic_none(mock_anthropic_client: MagicMock) -> None:
    """Test converting None tools."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)
+    chat_options = ChatOptions()

-    result = chat_client._convert_tools_to_anthropic_format(None)
+    result = chat_client._prepare_tools_for_anthropic(chat_options)

    assert result is None

@@ -373,14 +375,14 @@ def test_convert_tools_to_anthropic_format_none(mock_anthropic_client: MagicMock
 # Run Options Tests


-async def test_create_run_options_basic(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with basic ChatOptions."""
+async def test_prepare_options_basic(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with basic ChatOptions."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [ChatMessage(role=Role.USER, text="Hello")]
    chat_options = ChatOptions(max_tokens=100, temperature=0.7)

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["model"] == chat_client.model_id
    assert run_options["max_tokens"] == 100
@@ -388,8 +390,8 @@ async def test_create_run_options_basic(mock_anthropic_client: MagicMock) -> Non
    assert "messages" in run_options


-async def test_create_run_options_with_system_message(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with system message."""
+async def test_prepare_options_with_system_message(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with system message."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [
@@ -398,52 +400,52 @@ async def test_create_run_options_with_system_message(mock_anthropic_client: Mag
    ]
    chat_options = ChatOptions()

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["system"] == "You are helpful."
    assert len(run_options["messages"]) == 1  # System message not in messages list


-async def test_create_run_options_with_tool_choice_auto(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with auto tool choice."""
+async def test_prepare_options_with_tool_choice_auto(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with auto tool choice."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [ChatMessage(role=Role.USER, text="Hello")]
    chat_options = ChatOptions(tool_choice="auto")

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["tool_choice"]["type"] == "auto"


-async def test_create_run_options_with_tool_choice_required(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with required tool choice."""
+async def test_prepare_options_with_tool_choice_required(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with required tool choice."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [ChatMessage(role=Role.USER, text="Hello")]
    # For required with specific function, need to pass as dict
    chat_options = ChatOptions(tool_choice={"mode": "required", "required_function_name": "get_weather"})

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["tool_choice"]["type"] == "tool"
    assert run_options["tool_choice"]["name"] == "get_weather"


-async def test_create_run_options_with_tool_choice_none(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with none tool choice."""
+async def test_prepare_options_with_tool_choice_none(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with none tool choice."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [ChatMessage(role=Role.USER, text="Hello")]
    chat_options = ChatOptions(tool_choice="none")

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["tool_choice"]["type"] == "none"


-async def test_create_run_options_with_tools(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with tools."""
+async def test_prepare_options_with_tools(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with tools."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    @ai_function
@@ -454,32 +456,32 @@ async def test_create_run_options_with_tools(mock_anthropic_client: MagicMock) -
    messages = [ChatMessage(role=Role.USER, text="Hello")]
    chat_options = ChatOptions(tools=[get_weather])

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert "tools" in run_options
    assert len(run_options["tools"]) == 1


-async def test_create_run_options_with_stop_sequences(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with stop sequences."""
+async def test_prepare_options_with_stop_sequences(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with stop sequences."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [ChatMessage(role=Role.USER, text="Hello")]
    chat_options = ChatOptions(stop=["STOP", "END"])

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["stop_sequences"] == ["STOP", "END"]


-async def test_create_run_options_with_top_p(mock_anthropic_client: MagicMock) -> None:
-    """Test _create_run_options with top_p."""
+async def test_prepare_options_with_top_p(mock_anthropic_client: MagicMock) -> None:
+    """Test _prepare_options with top_p."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    messages = [ChatMessage(role=Role.USER, text="Hello")]
    chat_options = ChatOptions(top_p=0.9)

-    run_options = chat_client._create_run_options(messages, chat_options)
+    run_options = chat_client._prepare_options(messages, chat_options)

    assert run_options["top_p"] == 0.9

@@ -540,41 +542,41 @@ def test_process_message_with_tool_use(mock_anthropic_client: MagicMock) -> None
    assert response.finish_reason == FinishReason.TOOL_CALLS


-def test_parse_message_usage_basic(mock_anthropic_client: MagicMock) -> None:
-    """Test _parse_message_usage with basic usage."""
+def test_parse_usage_from_anthropic_basic(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_usage_from_anthropic with basic usage."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    usage = BetaUsage(input_tokens=10, output_tokens=5)
-    result = chat_client._parse_message_usage(usage)
+    result = chat_client._parse_usage_from_anthropic(usage)

    assert result is not None
    assert result.input_token_count == 10
    assert result.output_token_count == 5


-def test_parse_message_usage_none(mock_anthropic_client: MagicMock) -> None:
-    """Test _parse_message_usage with None usage."""
+def test_parse_usage_from_anthropic_none(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_usage_from_anthropic with None usage."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

-    result = chat_client._parse_message_usage(None)
+    result = chat_client._parse_usage_from_anthropic(None)

    assert result is None


-def test_parse_message_contents_text(mock_anthropic_client: MagicMock) -> None:
-    """Test _parse_message_contents with text content."""
+def test_parse_contents_from_anthropic_text(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_contents_from_anthropic with text content."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    content = [BetaTextBlock(type="text", text="Hello!")]
-    result = chat_client._parse_message_contents(content)
+    result = chat_client._parse_contents_from_anthropic(content)

    assert len(result) == 1
    assert isinstance(result[0], TextContent)
    assert result[0].text == "Hello!"


-def test_parse_message_contents_tool_use(mock_anthropic_client: MagicMock) -> None:
-    """Test _parse_message_contents with tool use."""
+def test_parse_contents_from_anthropic_tool_use(mock_anthropic_client: MagicMock) -> None:
+    """Test _parse_contents_from_anthropic with tool use."""
    chat_client = create_test_anthropic_client(mock_anthropic_client)

    content = [
@@ -585,7 +587,7 @@ def test_parse_message_contents_tool_use(mock_anthropic_client: MagicMock) -> No
            input={"location": "SF"},
        )
    ]
-    result = chat_client._parse_message_contents(content)
+    result = chat_client._parse_contents_from_anthropic(content)

    assert len(result) == 1
    assert isinstance(result[0], FunctionCallContent)
@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251211"
+version = "1.0.0b251216"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -43,7 +43,7 @@ from agent_framework import (
    use_function_invocation,
 )
 from agent_framework.exceptions import ServiceInitializationError, ServiceResponseException
-from agent_framework.observability import use_observability
+from agent_framework.observability import use_instrumentation
 from azure.ai.agents.aio import AgentsClient
 from azure.ai.agents.models import (
    Agent,
@@ -107,7 +107,7 @@ TAzureAIAgentClient = TypeVar("TAzureAIAgentClient", bound="AzureAIAgentClient")


@use_function_invocation
-@use_observability
+@use_instrumentation
@use_chat_middleware
 class AzureAIAgentClient(BaseChatClient):
    """Azure AI Agent Chat client."""
@@ -278,22 +278,13 @@ class AzureAIAgentClient(BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> AsyncIterable[ChatResponseUpdate]:
-        # Extract necessary state from messages and options
-        run_options, required_action_results = await self._create_run_options(messages, chat_options, **kwargs)
-
-        # Get the thread ID
-        thread_id: str | None = (
-            chat_options.conversation_id
-            if chat_options.conversation_id is not None
-            else run_options.get("conversation_id", self.thread_id)
-        )
-
-        # Determine which agent to use and create if needed
+        # prepare
+        run_options, required_action_results = await self._prepare_options(messages, chat_options, **kwargs)
        agent_id = await self._get_agent_id_or_create(run_options)

-        # Process and yield each update from the stream
+        # execute and process
        async for update in self._process_stream(
-            *(await self._create_agent_stream(thread_id, agent_id, run_options, required_action_results))
+            *(await self._create_agent_stream(agent_id, run_options, required_action_results))
        ):
            yield update

@@ -342,7 +333,6 @@ class AzureAIAgentClient(BaseChatClient):

    async def _create_agent_stream(
        self,
-        thread_id: str | None,
        agent_id: str,
        run_options: dict[str, Any],
        required_action_results: list[FunctionResultContent | FunctionApprovalResponseContent] | None,
@@ -352,14 +342,14 @@ class AzureAIAgentClient(BaseChatClient):
        Returns:
            tuple: (stream, final_thread_id)
        """
+        thread_id = run_options.pop("thread_id", None)
+
        # Get any active run for this thread
        thread_run = await self._get_active_thread_run(thread_id)

        stream: AsyncAgentRunStream[AsyncAgentEventHandler[Any]] | AsyncAgentEventHandler[Any]
        handler: AsyncAgentEventHandler[Any] = AsyncAgentEventHandler()
-        tool_run_id, tool_outputs, tool_approvals = self._convert_required_action_to_tool_output(
-            required_action_results
-        )
+        tool_run_id, tool_outputs, tool_approvals = self._prepare_tool_outputs_for_azure_ai(required_action_results)

        if (
            thread_run is not None
@@ -421,19 +411,11 @@ class AzureAIAgentClient(BaseChatClient):

        # No thread ID was provided, so create a new thread.
        thread = await self.agents_client.threads.create(
-            tool_resources=run_options.get("tool_resources"), metadata=run_options.get("metadata")
+            tool_resources=run_options.get("tool_resources"),
+            metadata=run_options.get("metadata"),
+            messages=run_options.get("additional_messages"),
        )
-        thread_id = thread.id
-        # workaround for: https://github.com/Azure/azure-sdk-for-python/issues/42805
-        # this occurs when otel is enabled
-        # once fixed, in the function above, readd:
-        # `messages=run_options.pop("additional_messages")`
-        for msg in run_options.pop("additional_messages", []):
-            await self.agents_client.messages.create(
-                thread_id=thread_id, role=msg.role, content=msg.content, metadata=msg.metadata
-            )
-        # and remove until here.
-        return thread_id
+        return thread.id

    def _extract_url_citations(
        self, message_delta_chunk: MessageDeltaChunk, azure_search_tool_calls: list[dict[str, Any]]
@@ -611,7 +593,7 @@ class AzureAIAgentClient(BaseChatClient):
                                    "submit_tool_outputs",
                                    "submit_tool_approval",
                                ]:
-                                    function_call_contents = self._create_function_call_contents(
+                                    function_call_contents = self._parse_function_calls_from_azure_ai(
                                        event_data, response_id
                                    )
                                    if function_call_contents:
@@ -753,8 +735,8 @@ class AzureAIAgentClient(BaseChatClient):
        except Exception as ex:
            logger.debug(f"Failed to capture Azure AI Search tool call: {ex}")

-    def _create_function_call_contents(self, event_data: ThreadRun, response_id: str | None) -> list[Contents]:
-        """Create function call contents from a tool action event."""
+    def _parse_function_calls_from_azure_ai(self, event_data: ThreadRun, response_id: str | None) -> list[Contents]:
+        """Parse function call contents from an Azure AI tool action event."""
        if isinstance(event_data, ThreadRun) and event_data.required_action is not None:
            if isinstance(event_data.required_action, SubmitToolOutputsAction):
                return [
@@ -815,117 +797,197 @@ class AzureAIAgentClient(BaseChatClient):

        chat_options.tool_choice = chat_tool_mode

-    async def _create_run_options(
+    async def _prepare_options(
        self,
        messages: MutableSequence[ChatMessage],
-        chat_options: ChatOptions | None,
+        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> tuple[dict[str, Any], list[FunctionResultContent | FunctionApprovalResponseContent] | None]:
-        run_options: dict[str, Any] = {**kwargs}
-
        agent_definition = await self._load_agent_definition_if_needed()

-        if chat_options is not None:
-            run_options["max_completion_tokens"] = chat_options.max_tokens
-            if chat_options.model_id is not None:
-                run_options["model"] = chat_options.model_id
-            else:
-                run_options["model"] = self.model_id
-            run_options["top_p"] = chat_options.top_p
-            run_options["temperature"] = chat_options.temperature
-            run_options["parallel_tool_calls"] = chat_options.allow_multiple_tool_calls
+        # Use to_dict with exclusions for properties handled separately
+        run_options: dict[str, Any] = chat_options.to_dict(
+            exclude={
+                "type",
+                "instructions",  # handled via messages
+                "tools",  # handled separately
+                "tool_choice",  # handled separately
+                "response_format",  # handled separately
+                "additional_properties",  # handled separately
+                "frequency_penalty",  # not supported
+                "presence_penalty",  # not supported
+                "user",  # not supported
+                "stop",  # not supported
+                "logit_bias",  # not supported
+                "seed",  # not supported
+                "store",  # not supported
+            }
+        )

-            tool_definitions: list[ToolDefinition | dict[str, Any]] = []
+        # Translation between ChatOptions and Azure AI Agents API
+        translations = {
+            "model_id": "model",
+            "allow_multiple_tool_calls": "parallel_tool_calls",
+            "max_tokens": "max_completion_tokens",
+        }
+        for old_key, new_key in translations.items():
+            if old_key in run_options and old_key != new_key:
+                run_options[new_key] = run_options.pop(old_key)

-            # Add tools from existing agent
-            if agent_definition is not None:
-                # Don't include function tools, since they will be passed through chat_options.tools
-                agent_tools = [tool for tool in agent_definition.tools if not isinstance(tool, FunctionToolDefinition)]
-                if agent_tools:
-                    tool_definitions.extend(agent_tools)
-                if agent_definition.tool_resources:
-                    run_options["tool_resources"] = agent_definition.tool_resources
+        # model id fallback
+        if not run_options.get("model"):
+            run_options["model"] = self.model_id

-            if chat_options.tool_choice is not None:
-                if chat_options.tool_choice != "none" and chat_options.tools:
-                    # Add run tools
-                    tool_definitions.extend(await self._prep_tools(chat_options.tools, run_options))
+        # tools and tool_choice
+        if tool_definitions := await self._prepare_tool_definitions_and_resources(
+            chat_options, agent_definition, run_options
+        ):
+            run_options["tools"] = tool_definitions

-                    # Handle MCP tool resources for approval mode
-                    mcp_tools = [tool for tool in chat_options.tools if isinstance(tool, HostedMCPTool)]
-                    if mcp_tools:
-                        mcp_resources = []
-                        for mcp_tool in mcp_tools:
-                            server_label = mcp_tool.name.replace(" ", "_")
-                            mcp_resource: dict[str, Any] = {"server_label": server_label}
+        if tool_choice := self._prepare_tool_choice_mode(chat_options):
+            run_options["tool_choice"] = tool_choice

-                            # Add headers if they exist
-                            if mcp_tool.headers:
-                                mcp_resource["headers"] = mcp_tool.headers
-
-                            if mcp_tool.approval_mode is not None:
-                                match mcp_tool.approval_mode:
-                                    case str():
-                                        # Map agent framework approval modes to Azure AI approval modes
-                                        approval_mode = (
-                                            "always" if mcp_tool.approval_mode == "always_require" else "never"
-                                        )
-                                        mcp_resource["require_approval"] = approval_mode
-                                    case _:
-                                        if "always_require_approval" in mcp_tool.approval_mode:
-                                            mcp_resource["require_approval"] = {
-                                                "always": mcp_tool.approval_mode["always_require_approval"]
-                                            }
-                                        elif "never_require_approval" in mcp_tool.approval_mode:
-                                            mcp_resource["require_approval"] = {
-                                                "never": mcp_tool.approval_mode["never_require_approval"]
-                                            }
-
-                            mcp_resources.append(mcp_resource)
-
-                        # Add MCP resources to tool_resources
-                        if "tool_resources" not in run_options:
-                            run_options["tool_resources"] = {}
-                        run_options["tool_resources"]["mcp"] = mcp_resources
-
-                if chat_options.tool_choice == "none":
-                    run_options["tool_choice"] = AgentsToolChoiceOptionMode.NONE
-                elif chat_options.tool_choice == "auto":
-                    run_options["tool_choice"] = AgentsToolChoiceOptionMode.AUTO
-                elif (
-                    isinstance(chat_options.tool_choice, ToolMode)
-                    and chat_options.tool_choice == "required"
-                    and chat_options.tool_choice.required_function_name is not None
-                ):
-                    run_options["tool_choice"] = AgentsNamedToolChoice(
-                        type=AgentsNamedToolChoiceType.FUNCTION,
-                        function=FunctionName(name=chat_options.tool_choice.required_function_name),
-                    )
-
-            if tool_definitions:
-                run_options["tools"] = tool_definitions
-
-            if chat_options.response_format is not None:
-                run_options["response_format"] = ResponseFormatJsonSchemaType(
-                    json_schema=ResponseFormatJsonSchema(
-                        name=chat_options.response_format.__name__,
-                        schema=chat_options.response_format.model_json_schema(),
-                    )
+        # response format
+        if chat_options.response_format is not None:
+            run_options["response_format"] = ResponseFormatJsonSchemaType(
+                json_schema=ResponseFormatJsonSchema(
+                    name=chat_options.response_format.__name__,
+                    schema=chat_options.response_format.model_json_schema(),
                )
+            )

+        # messages
+        additional_messages, instructions, required_action_results = self._prepare_messages(messages)
+        if additional_messages:
+            run_options["additional_messages"] = additional_messages
+
+        # Add instruction from existing agent at the beginning
+        if (
+            agent_definition is not None
+            and agent_definition.instructions
+            and agent_definition.instructions not in instructions
+        ):
+            instructions.insert(0, agent_definition.instructions)
+
+        if instructions:
+            run_options["instructions"] = "\n".join(instructions)
+
+        # thread_id resolution (conversation_id takes precedence, then kwargs, then instance default)
+        run_options["thread_id"] = chat_options.conversation_id or kwargs.get("conversation_id") or self.thread_id
+
+        return run_options, required_action_results
+
+    def _prepare_tool_choice_mode(
+        self, chat_options: ChatOptions
+    ) -> AgentsToolChoiceOptionMode | AgentsNamedToolChoice | None:
+        """Prepare the tool choice mode for Azure AI Agents API."""
+        if chat_options.tool_choice is None:
+            return None
+        if chat_options.tool_choice == "none":
+            return AgentsToolChoiceOptionMode.NONE
+        if chat_options.tool_choice == "auto":
+            return AgentsToolChoiceOptionMode.AUTO
+        if (
+            isinstance(chat_options.tool_choice, ToolMode)
+            and chat_options.tool_choice == "required"
+            and chat_options.tool_choice.required_function_name is not None
+        ):
+            return AgentsNamedToolChoice(
+                type=AgentsNamedToolChoiceType.FUNCTION,
+                function=FunctionName(name=chat_options.tool_choice.required_function_name),
+            )
+        return None
+
+    async def _prepare_tool_definitions_and_resources(
+        self,
+        chat_options: ChatOptions,
+        agent_definition: Agent | None,
+        run_options: dict[str, Any],
+    ) -> list[ToolDefinition | dict[str, Any]]:
+        """Prepare tool definitions and resources for the run options."""
+        tool_definitions: list[ToolDefinition | dict[str, Any]] = []
+
+        # Add tools from existing agent (exclude function tools - passed via chat_options.tools)
+        if agent_definition is not None:
+            agent_tools = [tool for tool in agent_definition.tools if not isinstance(tool, FunctionToolDefinition)]
+            if agent_tools:
+                tool_definitions.extend(agent_tools)
+            if agent_definition.tool_resources:
+                run_options["tool_resources"] = agent_definition.tool_resources
+
+        # Add run tools if tool_choice allows
+        if chat_options.tool_choice is not None and chat_options.tool_choice != "none" and chat_options.tools:
+            tool_definitions.extend(await self._prepare_tools_for_azure_ai(chat_options.tools, run_options))
+
+            # Handle MCP tool resources
+            mcp_resources = self._prepare_mcp_resources(chat_options.tools)
+            if mcp_resources:
+                if "tool_resources" not in run_options:
+                    run_options["tool_resources"] = {}
+                run_options["tool_resources"]["mcp"] = mcp_resources
+
+        return tool_definitions
+
+    def _prepare_mcp_resources(
+        self, tools: Sequence["ToolProtocol | MutableMapping[str, Any]"]
+    ) -> list[dict[str, Any]]:
+        """Prepare MCP tool resources for approval mode configuration."""
+        mcp_tools = [tool for tool in tools if isinstance(tool, HostedMCPTool)]
+        if not mcp_tools:
+            return []
+
+        mcp_resources: list[dict[str, Any]] = []
+        for mcp_tool in mcp_tools:
+            server_label = mcp_tool.name.replace(" ", "_")
+            mcp_resource: dict[str, Any] = {"server_label": server_label}
+
+            if mcp_tool.headers:
+                mcp_resource["headers"] = mcp_tool.headers
+
+            if mcp_tool.approval_mode is not None:
+                match mcp_tool.approval_mode:
+                    case str():
+                        # Map agent framework approval modes to Azure AI approval modes
+                        approval_mode = "always" if mcp_tool.approval_mode == "always_require" else "never"
+                        mcp_resource["require_approval"] = approval_mode
+                    case _:
+                        if "always_require_approval" in mcp_tool.approval_mode:
+                            mcp_resource["require_approval"] = {
+                                "always": mcp_tool.approval_mode["always_require_approval"]
+                            }
+                        elif "never_require_approval" in mcp_tool.approval_mode:
+                            mcp_resource["require_approval"] = {
+                                "never": mcp_tool.approval_mode["never_require_approval"]
+                            }
+
+            mcp_resources.append(mcp_resource)
+
+        return mcp_resources
+
+    def _prepare_messages(
+        self, messages: MutableSequence[ChatMessage]
+    ) -> tuple[
+        list[ThreadMessageOptions] | None,
+        list[str],
+        list[FunctionResultContent | FunctionApprovalResponseContent] | None,
+    ]:
+        """Prepare messages for Azure AI Agents API.
+
+        System/developer messages are turned into instructions, since there is no such message roles in Azure AI.
+        All other messages are added 1:1, treating assistant messages as agent messages
+        and everything else as user messages.
+
+        Returns:
+            Tuple of (additional_messages, instructions, required_action_results)
+        """
        instructions: list[str] = []
        required_action_results: list[FunctionResultContent | FunctionApprovalResponseContent] | None = None
-
        additional_messages: list[ThreadMessageOptions] | None = None

-        # System/developer messages are turned into instructions, since there is no such message roles in Azure AI.
-        # All other messages are added 1:1, treating assistant messages as agent messages
-        # and everything else as user messages.
        for chat_message in messages:
            if chat_message.role.value in ["system", "developer"]:
                for text_content in [content for content in chat_message.contents if isinstance(content, TextContent)]:
                    instructions.append(text_content.text)
-
                continue

            message_contents: list[MessageInputContentBlock] = []
@@ -942,7 +1004,7 @@ class AzureAIAgentClient(BaseChatClient):
                elif isinstance(content.raw_representation, MessageInputContentBlock):
                    message_contents.append(content.raw_representation)

-            if len(message_contents) > 0:
+            if message_contents:
                if additional_messages is None:
                    additional_messages = []
                additional_messages.append(
@@ -952,26 +1014,12 @@ class AzureAIAgentClient(BaseChatClient):
                    )
                )

-        if additional_messages is not None:
-            run_options["additional_messages"] = additional_messages
+        return additional_messages, instructions, required_action_results

-        # Add instruction from existing agent at the beginning
-        if (
-            agent_definition is not None
-            and agent_definition.instructions
-            and agent_definition.instructions not in instructions
-        ):
-            instructions.insert(0, agent_definition.instructions)
-
-        if len(instructions) > 0:
-            run_options["instructions"] = "".join(instructions)
-
-        return run_options, required_action_results
-
-    async def _prep_tools(
+    async def _prepare_tools_for_azure_ai(
        self, tools: Sequence["ToolProtocol | MutableMapping[str, Any]"], run_options: dict[str, Any] | None = None
    ) -> list[ToolDefinition | dict[str, Any]]:
-        """Prepare tool definitions for the run options."""
+        """Prepare tool definitions for the Azure AI Agents API."""
        tool_definitions: list[ToolDefinition | dict[str, Any]] = []
        for tool in tools:
            match tool:
@@ -1044,10 +1092,11 @@ class AzureAIAgentClient(BaseChatClient):
                    raise ServiceInitializationError(f"Unsupported tool type: {type(tool)}")
        return tool_definitions

-    def _convert_required_action_to_tool_output(
+    def _prepare_tool_outputs_for_azure_ai(
        self,
        required_action_results: list[FunctionResultContent | FunctionApprovalResponseContent] | None,
    ) -> tuple[str | None, list[ToolOutput] | None, list[ToolApproval] | None]:
+        """Prepare function results and approvals for submission to the Azure AI API."""
        run_id: str | None = None
        tool_outputs: list[ToolOutput] | None = None
        tool_approvals: list[ToolApproval] | None = None
@@ -15,7 +15,7 @@ from agent_framework import (
    use_function_invocation,
 )
 from agent_framework.exceptions import ServiceInitializationError, ServiceInvalidRequestError
-from agent_framework.observability import use_observability
+from agent_framework.observability import use_instrumentation
 from agent_framework.openai._responses_client import OpenAIBaseResponsesClient
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import (
@@ -28,10 +28,6 @@ from azure.ai.projects.models import (
 )
 from azure.core.credentials_async import AsyncTokenCredential
 from azure.core.exceptions import ResourceNotFoundError
-from openai.types.responses.parsed_response import (
-    ParsedResponse,
-)
-from openai.types.responses.response import Response as OpenAIResponse
 from pydantic import BaseModel, ValidationError

 from ._shared import AzureAISettings
@@ -41,6 +37,11 @@ if sys.version_info >= (3, 11):
 else:
    from typing_extensions import Self  # pragma: no cover

+if sys.version_info >= (3, 12):
+    from typing import override  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import override  # type: ignore[import] # pragma: no cover
+

 logger = get_logger("agent_framework.azure")

@@ -49,7 +50,7 @@ TAzureAIClient = TypeVar("TAzureAIClient", bound="AzureAIClient")


@use_function_invocation
-@use_observability
+@use_instrumentation
@use_chat_middleware
 class AzureAIClient(OpenAIBaseResponsesClient):
    """Azure AI Agent client."""
@@ -164,27 +165,94 @@ class AzureAIClient(OpenAIBaseResponsesClient):
        # Track whether we should close client connection
        self._should_close_client = should_close_client

-    async def setup_azure_ai_observability(self, enable_sensitive_data: bool | None = None) -> None:
-        """Use this method to setup tracing in your Azure AI Project.
+    async def configure_azure_monitor(
+        self,
+        enable_sensitive_data: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Setup observability with Azure Monitor (Azure AI Foundry integration).

-        This will take the connection string from the project project_client.
-        It will override any connection string that is set in the environment variables.
-        It will disable any OTLP endpoint that might have been set.
+        This method configures Azure Monitor for telemetry collection using the
+        connection string from the Azure AI project client.
+
+        Args:
+            enable_sensitive_data: Enable sensitive data logging (prompts, responses).
+                Should only be enabled in development/test environments. Default is False.
+            **kwargs: Additional arguments passed to configure_azure_monitor().
+                Common options include:
+                - enable_live_metrics (bool): Enable Azure Monitor Live Metrics
+                - credential (TokenCredential): Azure credential for Entra ID auth
+                - resource (Resource): Custom OpenTelemetry resource
+                See https://learn.microsoft.com/python/api/azure-monitor-opentelemetry/azure.monitor.opentelemetry.configure_azure_monitor
+                for full list of options.
+
+        Raises:
+            ImportError: If azure-monitor-opentelemetry-exporter is not installed.
+
+        Examples:
+            .. code-block:: python
+
+                from agent_framework.azure import AzureAIClient
+                from azure.ai.projects.aio import AIProjectClient
+                from azure.identity.aio import DefaultAzureCredential
+
+                async with (
+                    DefaultAzureCredential() as credential,
+                    AIProjectClient(
+                        endpoint="https://your-project.api.azureml.ms", credential=credential
+                    ) as project_client,
+                    AzureAIClient(project_client=project_client) as client,
+                ):
+                    # Setup observability with defaults
+                    await client.configure_azure_monitor()
+
+                    # With live metrics enabled
+                    await client.configure_azure_monitor(enable_live_metrics=True)
+
+                    # With sensitive data logging (dev/test only)
+                    await client.configure_azure_monitor(enable_sensitive_data=True)
+
+        Note:
+            This method retrieves the Application Insights connection string from the
+            Azure AI project client automatically. You must have Application Insights
+            configured in your Azure AI project for this to work.
        """
+        # Get connection string from project client
        try:
            conn_string = await self.project_client.telemetry.get_application_insights_connection_string()
        except ResourceNotFoundError:
            logger.warning(
-                "No Application Insights connection string found for the Azure AI Project, "
-                "please call setup_observability() manually."
+                "No Application Insights connection string found for the Azure AI Project. "
+                "Please ensure Application Insights is configured in your Azure AI project, "
+                "or call configure_otel_providers() manually with custom exporters."
            )
            return
-        from agent_framework.observability import setup_observability

-        setup_observability(
-            applicationinsights_connection_string=conn_string, enable_sensitive_data=enable_sensitive_data
+        # Import Azure Monitor with proper error handling
+        try:
+            from azure.monitor.opentelemetry import configure_azure_monitor
+        except ImportError as exc:
+            raise ImportError(
+                "azure-monitor-opentelemetry is required for Azure Monitor integration. "
+                "Install it with: pip install azure-monitor-opentelemetry"
+            ) from exc
+
+        from agent_framework.observability import create_metric_views, create_resource, enable_instrumentation
+
+        # Create resource if not provided in kwargs
+        if "resource" not in kwargs:
+            kwargs["resource"] = create_resource()
+
+        # Configure Azure Monitor with connection string and kwargs
+        configure_azure_monitor(
+            connection_string=conn_string,
+            views=create_metric_views(),
+            **kwargs,
        )

+        # Complete setup with core observability
+        enable_instrumentation(enable_sensitive_data=enable_sensitive_data)
+
    async def __aenter__(self) -> "Self":
        """Async context manager entry."""
        return self
@@ -268,6 +336,10 @@ class AzureAIClient(OpenAIBaseResponsesClient):

            if "tools" in run_options:
                args["tools"] = run_options["tools"]
+            if "temperature" in run_options:
+                args["temperature"] = run_options["temperature"]
+            if "top_p" in run_options:
+                args["top_p"] = run_options["top_p"]

            if "response_format" in run_options:
                response_format = run_options["response_format"]
@@ -297,7 +369,38 @@ class AzureAIClient(OpenAIBaseResponsesClient):
        if self._should_close_client:
            await self.project_client.close()

-    def _prepare_input(self, messages: MutableSequence[ChatMessage]) -> tuple[list[ChatMessage], str | None]:
+    @override
+    async def _prepare_options(
+        self,
+        messages: MutableSequence[ChatMessage],
+        chat_options: ChatOptions,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Take ChatOptions and create the specific options for Azure AI."""
+        prepared_messages, instructions = self._prepare_messages_for_azure_ai(messages)
+        run_options = await super()._prepare_options(prepared_messages, chat_options, **kwargs)
+        if not self._is_application_endpoint:
+            # Application-scoped response APIs do not support "agent" property.
+            agent_reference = await self._get_agent_reference_or_create(run_options, instructions)
+            run_options["extra_body"] = {"agent": agent_reference}
+
+        # Remove properties that are not supported on request level
+        # but were configured on agent level
+        exclude = ["model", "tools", "response_format", "temperature", "top_p"]
+
+        for property in exclude:
+            run_options.pop(property, None)
+
+        return run_options
+
+    @override
+    def _get_current_conversation_id(self, chat_options: ChatOptions, **kwargs: Any) -> str | None:
+        """Get the current conversation ID from chat options or kwargs."""
+        return chat_options.conversation_id or kwargs.get("conversation_id") or self.conversation_id
+
+    def _prepare_messages_for_azure_ai(
+        self, messages: MutableSequence[ChatMessage]
+    ) -> tuple[list[ChatMessage], str | None]:
        """Prepare input from messages and convert system/developer messages to instructions."""
        result: list[ChatMessage] = []
        instructions_list: list[str] = []
@@ -316,44 +419,7 @@ class AzureAIClient(OpenAIBaseResponsesClient):

        return result, instructions

-    async def prepare_options(
-        self,
-        messages: MutableSequence[ChatMessage],
-        chat_options: ChatOptions,
-        **kwargs: Any,
-    ) -> dict[str, Any]:
-        """Take ChatOptions and create the specific options for Azure AI."""
-        prepared_messages, instructions = self._prepare_input(messages)
-        run_options = await super().prepare_options(prepared_messages, chat_options, **kwargs)
-
-        if not self._is_application_endpoint:
-            # Application-scoped response APIs do not support "agent" property.
-            agent_reference = await self._get_agent_reference_or_create(run_options, instructions)
-            run_options["extra_body"] = {"agent": agent_reference}
-
-        conversation_id = chat_options.conversation_id or self.conversation_id
-
-        # Handle different conversation ID formats
-        if conversation_id:
-            if conversation_id.startswith("resp_"):
-                # For response IDs, set previous_response_id and remove conversation property
-                run_options.pop("conversation", None)
-                run_options["previous_response_id"] = conversation_id
-            elif conversation_id.startswith("conv_"):
-                # For conversation IDs, set conversation and remove previous_response_id property
-                run_options.pop("previous_response_id", None)
-                run_options["conversation"] = conversation_id
-
-        # Remove properties that are not supported on request level
-        # but were configured on agent level
-        exclude = ["model", "tools", "response_format"]
-
-        for property in exclude:
-            run_options.pop(property, None)
-
-        return run_options
-
-    async def initialize_client(self) -> None:
+    async def _initialize_client(self) -> None:
        """Initialize OpenAI client."""
        self.client = self.project_client.get_openai_client()  # type: ignore

@@ -371,7 +437,8 @@ class AzureAIClient(OpenAIBaseResponsesClient):
        if description and not self.agent_description:
            self.agent_description = description

-    def get_mcp_tool(self, tool: HostedMCPTool) -> Any:
+    @staticmethod
+    def _prepare_mcp_tool(tool: HostedMCPTool) -> MCPTool:  # type: ignore[override]
        """Get MCP tool from HostedMCPTool."""
        mcp = MCPTool(server_label=tool.name.replace(" ", "_"), server_url=str(tool.url))

@@ -389,17 +456,3 @@ class AzureAIClient(OpenAIBaseResponsesClient):
                        mcp["require_approval"] = {"never": {"tool_names": list(never_require_approvals)}}

        return mcp
-
-    def get_conversation_id(
-        self, response: OpenAIResponse | ParsedResponse[BaseModel], store: bool | None
-    ) -> str | None:
-        """Get the conversation ID from the response if store is True."""
-        if store is False:
-            return None
-        # If conversation ID exists, it means that we operate with conversation
-        # so we use conversation ID as input and output.
-        if response.conversation and response.conversation.id:
-            return response.conversation.id
-        # If conversation ID doesn't exist, we operate with responses
-        # so we use response ID as input and output.
-        return response.id
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Evan MattsonandGitHub	b0a7a1fcb8	Python: Fix WorkflowAgent event handling and kwargs forwarding (#2946 ) * Fix kwargs propagation through workflow.as_agent() * Fix WorkflowAgent to respect AgentExecutor output_response setting	2025-12-18 19:35:07 +00:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>Chris	a841bdd1cc	Bump Azure.AI.AgentServer.AgentFramework from 1.0.0-beta.4 to 1.0.0-beta.5 (#2854 ) --- updated-dependencies: - dependency-name: Azure.AI.AgentServer.AgentFramework dependency-version: 1.0.0-beta.5 dependency-type: direct:production update-type: version-update:semver-patch - dependency-name: Azure.AI.AgentServer.AgentFramework dependency-version: 1.0.0-beta.5 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Chris <66376200+crickman@users.noreply.github.com>	2025-12-18 18:36:13 +00:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>Mark Wallace	d46adffe6c	Bump AWSSDK.Extensions.Bedrock.MEAI from 4.0.4.11 to 4.0.5 (#2853 ) --- updated-dependencies: - dependency-name: AWSSDK.Extensions.Bedrock.MEAI dependency-version: 4.0.5 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Mark Wallace <127216156+markwallace-microsoft@users.noreply.github.com>	2025-12-18 17:25:54 +00:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	b0b5777363	Bump CommunityToolkit.Aspire.OllamaSharp from 13.0.0-beta.440 to 13.0.0 (#2856 ) --- updated-dependencies: - dependency-name: CommunityToolkit.Aspire.OllamaSharp dependency-version: 13.0.0 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-12-18 17:25:36 +00:00
Giles OdigweandGitHub	37b4cfd024	Python: Add Azure Managed Redis Support with Credential Provider (#2887 ) * azure redis support * small fixes * azure managed redis sample * fixes	2025-12-18 17:10:55 +00:00
Copilot GitHub stephentoubcopilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>	ff9343d7cc	.NET: Update Anthropic package to version 12.0.0 (#2914 ) * Initial plan * Update Anthropic package to version 12.0.0 Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>	2025-12-18 16:02:20 +00:00
Victor DibiaandGitHub	8ff34f9a43	Python: Add workflow cancellation sample (#2732 ) * Add workflow cancellation sample Add sample demonstrating how to cancel a running workflow using asyncio tasks. Shows both cancellation mid-execution and normal completion paths. Useful for implementing timeouts, graceful shutdown, or A2A executors. * update docstring	2025-12-18 14:12:42 +00:00
Hao LuoandGitHub	e3f8bfc645	Python: Fixes Run ID and Thread ID casing to align with AG-UI Typescript SDK (#2948 ) * added camelCase input to run id and thread id aligning with @ag-ui/core * fixed per copilot suggestions	2025-12-18 14:10:16 +00:00
Tao ChenandGitHub	b4f2709b6d	Python: Workflow add option to visualize internal executors (#2917 ) * Workflow add option to visualize internal executors * Address Copilot comments	2025-12-18 14:04:03 +00:00
Eduard van ValkenburgandGitHub	e5c11d38d6	Python: cleanup and refactoring of chat clients (#2937 ) * refactoring and unifying naming schemes of internal methods of chat clients * set tool_choice to auto * fix for mypy * added note on naming and fix #2951 * fix responses * fixes in azure ai agents client	2025-12-18 12:02:23 +00:00
SergeyMenshykh GitHub Copilot	a71f768331	.NET: [Breaking] Delete display name property (#2758 ) * delete the AIAgent.DisplayName property * use agent name as a first value for activity display name * Update dotnet/src/Microsoft.Agents.AI.Workflows/Specialized/HandoffAgentExecutor.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-12-18 09:22:45 +00:00
samueljohnsiby GitHub Evan Mattson	0298e0a401	Python: fix: correct BadRequestError when using Pydantic model in response_fo… (#1843 ) * fix: correct BadRequestError when using Pydantic model in response_format * Fix lint --------- Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>	2025-12-18 08:42:00 +00:00
Evan MattsonandGitHub	ca1532cf22	Python: Move ollama samples to samples getting started dir (#2921 ) * Move ollama samples to samples getting started dir * Address feedback	2025-12-18 08:37:05 +00:00
Evan MattsonandGitHub	360839782c	Pass kwargs into subworkflows (#2923 )	2025-12-18 04:34:33 +00:00
Ege Ozan ÖzyedekandGitHub	ee53fe4666	Python: Correction of MCP image type conversion in _mcp.py (#2901 ) * Correction of MCP image type conversion in _mcp.py * Added a new overload to the init function of the DataContent() type of the Agent Framework, edited the test case to correctly test the usage of the data and uri fields while using DataContent() * Fixed tests related to the changes of the DataContent type, added testing for both string and byte representations	2025-12-17 16:11:39 +00:00
Dmytro StrukandGitHub	3cd805f0bf	Added additional arguments for Azure AI agent (#2922 )	2025-12-17 08:08:01 +00:00
Copilot GitHub SergeyMenshykhcopilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>	c7ddb8aa14	.NET: Make DelegatingAIAgent abstract (#2797 ) * Initial plan * Make DelegatingAIAgent abstract Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>	2025-12-17 07:31:10 +00:00
Giles OdigweandGitHub	d5527982b6	Python: Azure AI Agent with Bing Grounding Citations Sample (#2892 ) * bing grounding sample with citations * small fix * fix	2025-12-17 00:43:38 +00:00
Dmytro StrukandGitHub	ec1c5e9c11	Updated Ollama package version (#2920 )	2025-12-17 00:42:27 +00:00
Evan MattsonandGitHub	06cdcb93f0	Fix Pydantic error when using Literal type for tool params (#2893 )	2025-12-17 00:27:01 +00:00
Evan MattsonandGitHub	6adcac2e97	Python: Flow custom kwargs to agents via Workflow SharedState (#2894 ) * Flow custom kwargs to agents via SharedState * Address Copilot feedback * Improve sample typing * Fix test	2025-12-17 00:04:00 +00:00
Tao ChenandGitHub	8fca71e5ad	[BREAKING] Python: Add factory pattern to handoff orchestration builder (#2844 ) * WIP: Factory pattern to handoff * Add factory pattern to concurrent orchestration builder; Next: tests and sample verification * Add tests and improve comments * Fix mypy * Simplify handoff_simple.py * Simplify handoff_autonoumous.py and bug fix * Update readme * Address Copilot comments	2025-12-16 23:38:33 +00:00
Phillip HoffandGitHub	2bde58f915	Python: Switch to new "run" method name. (#2890 ) * Switch to `run` method. * Add support for deprecated `run_agent`. * Fix entity method name. * Fix method name and improve tests. * Update comment. * Update Python CHANGELOG.	2025-12-16 22:08:12 +00:00
Phillip HoffandGitHub	03a403d2fa	.NET: Switch to new "Run" method name. (#2843 ) * Switch to new "RunAgent" method name. * Try to disable false positive naming warning. * Add comment about disabled warnings. * Rename `RunAgent` to just `Run`. * Update CHANGELOG.	2025-12-16 22:07:59 +00:00
Dmytro StrukandGitHub	e319707058	Updated package versions (#2913 )	2025-12-16 18:51:44 +00:00
Giles OdigweandGitHub	54f482df73	Python: Update Mem0Provider to use v2 search API `filters` parameter (#2766 ) * short fix to move id parameters to filters object * added tests * small fix * mem0 dependency update	2025-12-16 18:23:37 +00:00
Chris GillumandGitHub	754dfb2c9d	.NET: Add TTLs to durable agent sessions (#2679 ) * .NET: Add TTLs to durable agent sessions * Remove unnecessary async * PR feedback: clarify UTC * PR feedback: limit minimum signal delay to <= 5 minutes * PR feedback: Fix TTL disablement * Linter: use auto-property * Fix build break from OpenAI SDK change * Updated CHANGELOG.md * PR feedback * Reduce default TTL to 14 days to work around DTS bug	2025-12-16 18:11:44 +00:00
Roger BarretoandGitHub	b15466f058	.NET: Cosmos DB UT Fast Skip (For Non-Configured Local envs) (#2906 ) * Cosmos DB UT Fast Skip (Non-Configured Local envs) + Long running UT skip in pipeline when no CosmosDB changes happened * Force a CosmosDB source code change to trigger the pipeline * Address possible string boolean mismatch * Add debug * Enabling emulator always when running IT	2025-12-16 17:37:41 +00:00
Roger BarretoandGitHub	3a7047f6e4	Skip failing IT (#2904 )	2025-12-16 17:21:22 +00:00
Nico Möller GitHub Copilot Eduard van Valkenburg	2f06fe557a	Python : Ollama Connector for Agent Framework (#1104 ) * Initial Commit for Olama Connector * Added Olama Sample * Add Sample & Fixed Open Telemetry * Fixed Spelling from Olama to Ollama * remove"opentelemetry-semantic-conventions-ai ~=0.4.13" since its handled in a different pr * Added Tool Calling * Finalizing test cases * Adjust samples to be more reliable * Update python/packages/ollama/agent_framework_ollama/_chat_client.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update python/packages/ollama/pyproject.toml Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update python/packages/ollama/tests/test_ollama_chat_client.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update python/packages/ollama/agent_framework_ollama/_chat_client.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Improved Docstrings & Sample * Update python/packages/ollama/agent_framework_ollama/_chat_client.py Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com> * Integrate PR Feedback - Divided Streaming and Non-Streaming into independent Methods - Catch Ollama Validation Error - Add OTEL Provider Name - Checked Ollama Messages - Add Usage Statistics * Revert setting, so it can be none * Validate Message formatting between AF and Ollama * Catch Ollama Error and raise a ServiceResponse Error * Fix mypy error * remove .vscode comma * Add Reasoning support & adjust to new structure * Add Ollama Multimodality and Reasoning * Add test cases for reasoning * Add Tests for Error Handling in Ollama Client * Update python/samples/getting_started/multimodal_input/ollama_chat_multimodal.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Integrated Copilot Feedback * Implement first PR Feedback * Adjust Readme files for examples * Adjust argument passing via additional chat options * Implemented PR Feedback * Removing Ollama Package from Core and moving samples * Fix Link & Adding Samples to Main Sample Readme * Fixing Links in Readme * Moved Multimodal and Chat Example * Fixed Link in ChatClient to Ollama * Fix AgentFramework Links in Ollama Project * Fix observability breaking change --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>	2025-12-16 15:02:38 +00:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	1dbf3fd5cf	Bump actions/upload-artifact from 5 to 6 (#2860 ) Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 5 to 6. - [Release notes](https://github.com/actions/upload-artifact/releases) - [Commits](https://github.com/actions/upload-artifact/compare/v5...v6) --- updated-dependencies: - dependency-name: actions/upload-artifact dependency-version: '6' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-12-16 13:39:56 +00:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	0132cf65e4	Bump actions/cache from 4 to 5 (#2861 ) Bumps [actions/cache](https://github.com/actions/cache) from 4 to 5. - [Release notes](https://github.com/actions/cache/releases) - [Changelog](https://github.com/actions/cache/blob/main/RELEASES.md) - [Commits](https://github.com/actions/cache/compare/v4...v5) --- updated-dependencies: - dependency-name: actions/cache dependency-version: '5' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-12-16 13:37:15 +00:00
dependabot[bot]GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	a53a3c7af8	Bump actions/download-artifact from 6 to 7 (#2862 ) Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 6 to 7. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](https://github.com/actions/download-artifact/compare/v6...v7) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-version: '7' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-12-16 13:36:56 +00:00
Stephen Toub GitHub Copilot Roger Barreto	3c322c91e7	.NET: Update to latest Azure.AI., OpenAI, and M.E.AI (#2850 ) * Update to latest Azure.AI., OpenAI, and M.E.AI Absorb breaking changes in Responses surface area * Update dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Utilities/ChatClientExtensions.cs * Update dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Utilities/ChatClientExtensions.cs * Update dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Utilities/ChatClientExtensions.cs * Update dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Program.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Using patch to remove the model is necessary, updated the response client to actually use the the ForAgent --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>	2025-12-16 12:41:20 +00:00
Evan MattsonandGitHub	958a488f96	Python: Fix context duplication in handoff workflows when restoring from checkpoint (#2867 ) * Fix context duplication in handoff workflows when restoring from checkpoint * Address Copilot PR review	2025-12-16 09:52:59 +00:00
Evan MattsonandGitHub	11d6dcfe80	Python: Fix middleware terminate flag to exit function calling loop immediately (#2868 ) * Fix middleware terminate flag to exit function calling loop immediately * Eliminating duck typing * Improve function exec result handling * Fix race condition * Fix mypy issues	2025-12-16 09:52:52 +00:00
Eduard van ValkenburgandGitHub	3139347526	Python: [BREAKING] Observability updates (#2782 ) * fixes Python: Add env_file_path parameter to setup_observability() similar to AzureOpenAIChatClient Fixes #2186 * WIP on updates using configure_azure_monitor * improved setup and clarity * fixed root .env.example * revert changes * updated files * updated sample * updated zero code * test fixes and fixed links * fix devui * removed planning docs * added enable method and updated readme and samples * clarified docstring * add return annotation * updated naming * update capatilized version * updated readme and some fixes * updated decorator name inline with the rest * feedback from comments addressed	2025-12-16 06:56:30 +00:00
刘邦学AI GitHub Evan Mattson	3c379718e9	Python: Use agent description in HandoffBuilder auto-generated tools (#2713 ) (#2714 ) ## Summary Enhanced `HandoffBuilder._apply_auto_tools` to use the target agent's description when creating handoff tools, providing more informative tool descriptions for LLMs. ## Changes - Modified `_apply_auto_tools` to extract `description` from `AgentExecutor._agent` when available - Updated iteration to use `.items()` for more efficient dict traversal - Handoff tools now use agent descriptions instead of generic placeholders ## Example Before: "Handoff to the refund_agent agent." After: "You handle refund requests. Ask for order details and process refunds." ## Testing - All handoff tests pass (20/20) - No breaking changes to existing API Fixes #2713 Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>	2025-12-16 01:31:26 +00:00
Evan MattsonandGitHub	a7298757f5	Python: Fix WorkflowAgent to emit yield_output as agent response (#2866 ) * Fix WorkflowAgent to emit yield_output as agent response * use raw_representation * Raw representation handling	2025-12-16 01:14:26 +00:00
Evan MattsonandGitHub	0dcebc6eae	Python: Filter framework kwargs from MCP tool invocations (#2870 ) * Filter framework kwargs from MCP tool invocations * Fixes	2025-12-16 01:10:09 +00:00
Tao ChenandGitHub	e0ff153ee9	Python: Remove warnings from workflow builder on not using factories (#2808 ) * Revert concurrent * Fix comments	2025-12-12 07:56:16 +00:00
Richard OrtegaandGitHub	e008144187	Update OpenAIResponses.yaml to match AgentSchema (#2598 ) 1. Update `connection` child types -- `kind: ApiKey` to `kind: key` otherwise schema will fail: https://microsoft.github.io/AgentSchema/reference/apikeyconnection/ 2. Update `outputSchema`'s `PropertySchema` to be `kind` instead of `type` otherwise schema will fail: https://microsoft.github.io/AgentSchema/reference/propertyschema/	2025-12-12 07:55:01 +00:00
Evan MattsonandGitHub	0fc7933a92	Fix WorkflowAgent to include thread convo history. Enable checkpointing. (#2774 )	2025-12-12 04:04:31 +00:00
Dmytro StrukandGitHub	d7434d59ce	Python: Added custom args and thread object to ai_function kwargs (#2769 ) * Added an example of using kwargs in ai_function * Added thread object to ai_function kwargs * Updated docs * Small fix * Added thread parameter filtering	2025-12-12 01:53:04 +00:00
Jose Luis Latorre Millas GitHub Copilot Jacob Alber Chris	eb1117fff4	.NET: adds support for labels in edges, fixes rendering of labels in dot a… (#1507 ) * adds support for labels in edges, fixes rendering of labels in dot and mermaid, adds rendering of labels in edges * Update dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * escaping edge labels, adding tests for labels containing strange characters that would break the diagram and enabling the previous signature so the API has backwards compatibility. * Unify label in EdgeData * Edge API adjustments, removed useless "sanitizer" * fixed test --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Jacob Alber <jaalber@microsoft.com> Co-authored-by: Chris <66376200+crickman@users.noreply.github.com>	2025-12-12 00:31:45 +00:00