From 0dd49e4a67f761fb307e8ed8e8e7b5e832af2826 Mon Sep 17 00:00:00 2001
From: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
Date: Tue, 16 Sep 2025 16:06:48 +0100
Subject: [PATCH] .NET: Add missing OpenAI `GetAIAgent` extensions (#690)

* Wip

* Add missing extensions for OpenAI agents

* Apply suggestion from @Copilot

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

* Remove duplicate xmldoc

* Address comment

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .../AssistantClientResultExtensions.cs        | 62 +++++++++++++++++++
 .../OpenAIAssistantClientExtensions.cs        | 57 +++++++++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/AssistantClientResultExtensions.cs

diff --git a/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/AssistantClientResultExtensions.cs b/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/AssistantClientResultExtensions.cs
new file mode 100644
index 0000000000..6faf65eacb
--- /dev/null
+++ b/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/AssistantClientResultExtensions.cs
@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ClientModel;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Agents;
+
+namespace OpenAI.Assistants;
+
+/// <summary>
+/// Provides extension methods for working with <see cref="ClientResult{Assistant}"/> where T is <see cref="Assistant"/>.
+/// </summary>
+public static class AssistantExtensions
+{
+    /// <summary>
+    /// Converts a <see cref="ClientResult{Assistant}"/> to a <see cref="ChatClientAgent"/>.
+    /// </summary>
+    /// <param name="assistantClientResult">The client result containing the assistant.</param>
+    /// <param name="assistantClient">The assistant client.</param>
+    /// <param name="chatOptions">Optional chat options.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the assistant.</returns>
+    public static ChatClientAgent AsAIAgent(this ClientResult<Assistant> assistantClientResult, AssistantClient assistantClient, ChatOptions? chatOptions = null)
+    {
+        if (assistantClientResult is null)
+        {
+            throw new ArgumentNullException(nameof(assistantClientResult));
+        }
+
+        return AssistantExtensions.AsAIAgent(assistantClientResult, assistantClient, chatOptions);
+    }
+
+    /// <summary>
+    /// Converts an <see cref="Assistant"/> to a <see cref="ChatClientAgent"/>.
+    /// </summary>
+    /// <param name="assistantMetadata">The assistant metadata.</param>
+    /// <param name="assistantClient">The assistant client.</param>
+    /// <param name="chatOptions">Optional chat options.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the assistant.</returns>
+    public static ChatClientAgent AsAIAgent(this Assistant assistantMetadata, AssistantClient assistantClient, ChatOptions? chatOptions = null)
+    {
+        if (assistantMetadata is null)
+        {
+            throw new ArgumentNullException(nameof(assistantMetadata));
+        }
+        if (assistantClient is null)
+        {
+            throw new ArgumentNullException(nameof(assistantClient));
+        }
+
+#pragma warning disable CA2000 // Dispose objects before losing scope
+        var chatClient = assistantClient.AsIChatClient(assistantMetadata.Id);
+#pragma warning restore CA2000 // Dispose objects before losing scope
+
+        return new ChatClientAgent(chatClient, options: new()
+        {
+            Id = assistantMetadata.Id,
+            Name = assistantMetadata.Name,
+            Description = assistantMetadata.Description,
+            Instructions = assistantMetadata.Instructions,
+            ChatOptions = chatOptions
+        });
+    }
+}
diff --git a/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/OpenAIAssistantClientExtensions.cs b/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/OpenAIAssistantClientExtensions.cs
index cfba779c1e..60cd192480 100644
--- a/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/OpenAIAssistantClientExtensions.cs
+++ b/dotnet/src/Microsoft.Extensions.AI.Agents.OpenAI/Extensions/OpenAIAssistantClientExtensions.cs
@@ -20,6 +20,63 @@ namespace OpenAI;
 /// </remarks>
 public static class OpenAIAssistantClientExtensions
 {
+    /// <summary>
+    /// Retrieves an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="AssistantClient"/>.
+    /// </summary>
+    /// <param name="assistantClient">The <see cref="AssistantClient"/> to create the <see cref="ChatClientAgent"/> with.</param>
+    /// <param name="agentId">The ID of the server side agent to create a <see cref="ChatClientAgent"/> for.</param>
+    /// <param name="chatOptions">Options that should apply to all runs of the agent.</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="ChatClientAgent"/> instance that can be used to perform operations on the assistant agent.</returns>
+    public static ChatClientAgent GetAIAgent(
+        this AssistantClient assistantClient,
+        string agentId,
+        ChatOptions? chatOptions = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (assistantClient is null)
+        {
+            throw new ArgumentNullException(nameof(assistantClient));
+        }
+
+        if (string.IsNullOrWhiteSpace(agentId))
+        {
+            throw new ArgumentException($"{nameof(agentId)} should not be null or whitespace.", nameof(agentId));
+        }
+
+        var assistant = assistantClient.GetAssistant(agentId, cancellationToken);
+        return assistant.AsAIAgent(assistantClient, chatOptions);
+    }
+
+    /// <summary>
+    /// Retrieves an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="AssistantClient"/>.
+    /// </summary>
+    /// <param name="assistantClient">The <see cref="AssistantClient"/> to create the <see cref="ChatClientAgent"/> with.</param>
+    /// <param name="agentId"> The ID of the server side agent to create a <see cref="ChatClientAgent"/> for.</param>
+    /// <param name="chatOptions">Options that should apply to all runs of the agent.</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="ChatClientAgent"/> instance that can be used to perform operations on the assistant agent.</returns>
+    public static async Task<ChatClientAgent> GetAIAgentAsync(
+        this AssistantClient assistantClient,
+        string agentId,
+        ChatOptions? chatOptions = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (assistantClient is null)
+        {
+            throw new ArgumentNullException(nameof(assistantClient));
+        }
+
+        if (string.IsNullOrWhiteSpace(agentId))
+        {
+            throw new ArgumentException($"{nameof(agentId)} should not be null or whitespace.", nameof(agentId));
+        }
+
+        var assistanceResponse = await assistantClient.GetAssistantAsync(agentId, cancellationToken).ConfigureAwait(false);
+
+        return assistanceResponse.AsAIAgent(assistantClient, chatOptions);
+    }
+
     /// <summary>
     /// Creates an AI agent from an <see cref="AssistantClient"/> using the OpenAI Assistant API.
     /// </summary>